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Preface 


Objectives 


This guide presents concepts and techniques for developing command 
procedures using the DIGITAL Command Language (DCL) on RSTS/E. 
Various examples, including complete command procedures, demonstrate 
applications of the concepts and techniques that this guide discusses. 


Audience 


All RSTS/E users can benefit from uSing command procedures. For 
example, you can place frequently used command sequences into a 
command procedure and thereby save keystrokes; you can also write 
sophisticated command sequences that pass parameters, test status 
values, process files, and perform similar program-like tasks. 


Although you do not have to be a computer expert to use this guide, 
you will have an easier time if you are familiar with programming 
concepts such as loops, logical values, and so forth. 


Document Structure 


Each chapter in this guide builds on material from earlier chapters. 
If command procedures are new to you, study this guide chapter by 
chapter beginning with Chapter 1. If you already have some knowledge 
of command procedures, you may want to skim the Table of Contents and 
Index for the specific topics you need. 


This manual contains nine chapters and four appendixes: 


Chapter 1 Defines command procedures and describes how to 
develop them. 


Chapter 2 Describes how to define and manipulate symbols. 
Chapter 3 Describes the use of expressions and operators. 
Chapter 4 Shows how to use the DCL functions to obtain 


information about the status of a process and to 
manipulate character strings. 


Chapter 5 Describes how to control input to and output from 
command procedures. 


Chapter 6 Explains how to manipulate files using command 
procedures. 


vil 


Chapter 7 


Chapter 8 


Chapter 9 


Appendix A 


Appendix B 


Appendix C 


Appendix D 


Related Documents 


Describes how to control the sequence in which 


command procedure lines are executed. 


Shows how to set up error handling routines based 
on the severity of errors encountered during 
command procedure execution and how to handle 
CTRL/C interrupts that occur during command 
procedure execution. 


Describes commands for displaying command 
procedure output. 


Contains sample command procedures that illustrate 
the techniques described in Chapters 1 through 9. 


Lists some of the major differences between the 
RSTS/E and VAX/VMS command processors. 


Lists the numeric values associated with RSTS/E 
error messages. 


Lists the ASCII character codes. 


This guide refers you to the following manuals for more detailed 


information: 


o RSTS/E System User’s Guide 


Oo RSTS/E System Manager’s Guide. 


Vill 


Conventions 


This manual uses the following symbols and conventions: 


[ ] Square brackets show the optional parts of a command in 
format statements. For example: 


DIRECTORY [file-spec[,...]] 


The square brackets in this example indicate that you 
can include a file specification ([file-spec]), or more 
than one ([,...]), if you choose. 


Square brackets also indicate the choice you have in 
using a command. For example: 


/[NO]DELETE 


This means you can type either /DELETE or /NODELETE, 
depending on the form of the qualifier you select. 


Do not confuse the square brackets in command formats 
with the square brackets in Project-Programmer numbers 
(PPNs), as in [52,20]. 


<CTRL/x> The control key, which you use in combination with 
another key. For example, enter CTRL/U by holding down 
the CTRL key and pressing the keyboard key labeled "U." 
RSTS/E displays, or echoes, CTRL/U at your terminal, as 
~y. | 


<RET> The key labeled RETURN on your terminal. You press the 
RETURN key to complete lines and commands that the 
system will process. 


color In examples, black characters are data produced by the 
computer. 


Red characters indicate information that you type. 
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Chapter 1l 


Introduction 


This chapter introduces command procedures and tells you how to 
develop them. 


What are Command Procedures? 


Command procedures are files that contain DCL commands. To execute 
these commands, you run the procedure. Use command procedures to 
execute sequences of commands you use during interactive terminal 
sessions or to execute commands you submit for batch processing. As 
you become more experienced in creating and using command procedures, 
you will find many other applications for them. 


Command procedures can range from simple to complex. A simple command 
procedure consists of one or more command lines for the DCL command 
interpreter to execute. For example, the following command procedure 
deletes all temporary (.TMP) files and then shows a directory listing: 


DIRECT.COM 
S$ ! Delete .TMP files and show directory 
S DELETE *.TMP 
S DIRECTORY 


A more complex command procedure performs program-like functions. It 
can: 


o Contain loops and error checking routines 


o Perform arithmetic calculations and input/output (1/0) 
operations 


Oo Manipulate character string data 


o Call or pass parameters to other command procedures 
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For example, the following command procedure edits all occurrences of 
files with a .B2S file type in a user’s account: 


B2S.COM 
S ! Edit all .B2S files 
S SET NODATA 
S NEXTFILE = FSSEARCH("SY:*.B2S") 
S LOOP: 
S IF NEXTFILE .EQS. "" THEN EXIT 
S EDIT/EDT 'NEXTFILE’ 
S NEXTFILE = FSSEARCH() 
S$ GOTO LOOP 


| Creating Command Procedures 


To create a command procedure, use a text editor such as EDT or the 
DCL CREATE command. The following example shows how to create a 
Simple command procedure using EDT: 


S EDIT/EDT RUN.COM <RET> 
Input file does not exist 

[ EOB ] 

*C <RET> 

S !Run three programs <RET> 
$ RUN PROG] <RET> 

S$ RUN PROG2 <RET> 

$ RUN PROG3 <RET> 


<CTRL/Z> 

*EXIT 

RUN -COM 3 lines 
=) 


The next example shows how to create the same procedure using the DCL 
CREATE command: 


S CREATE RUN.COM <RET> 

S !Run three programs <RET> 
S RUN PROG] <RET> 

S RUN PROG2 <RET> 

S RUN PROG3 <RET> 

<CTRL/Z> 

3 


Note that the examples use the file type .COM. When you execute a 
command procedure, DCL uses this file type as the default. 
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Formatting Command Procedures 


Follow these format conventions and restrictions when you create a 
command procedure: 


O 


Begin each DCL command line with a dollar sign ($) character 
in the first space of the line -- Using this character 
ensures that DCL processes the command when you execute the 
procedure from another keyboard monitor such as BASIC-PLUS. 


Begin each line containing a DCL label with a $ character in 
the first space of the line -- Put labels on separate lines 
to help make loops and conditional coding easier to 
understand. 


Do NOT begin the following types of lines with the $§$ 
character: 


- Data lines 
- Command lines to keyboard monitors other than DCL 


- DCL continuation lines 


Separate command sequences -- Insert lines containing only a 
S$ character before and after a logical sequence of commands. 
This convention makes it easier to see the structure of the 

command procedure. 


Avoid abbreviating DCL keywords to less than 4 characters -- 
DCL conventions ensure that all qualifiers and keywords are 
unique in the first 4 characters. 


Use comments -- Comments explain the procedure to anyone who 
must maintain it; DCL ignores them during execution. You 
begin comments with an exclamation point and place the 


comment to the right of the exclamation point. You can place 


a comment on a separate command line or at the end of a 
command line. If a comment exceeds one line, place an 
exclamation point at the start of each line. 


Use comments at the beginning of a procedure to describe the 
procedure and the parameters you pass to it or use them at 
the beginning of each block of commands to describe that 
section of the procedure. However, note that excessive use 
of comments can decrease performance. 
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Executing Command Procedures 


You can execute command procedures in many different ways on RSTS/E 
systems: 


o At login time, RSTS automatically executes the system-wide 
LOGIN.COM file and any private LOGIN.COM file 


o At interactive level, using the at sign (@) command, or from 
any other keyboard monitor using the $@ combination 


o In batch mode, using the SUBMIT command 
Oo From inside another command procedure (nesting) 


o With the RUN command from any keyboard monitor, provided the 
command file is executable and includes the DCL run-time 
system attribute 


o With the CHAIN statement from another program, provided the 
command file is executable and includes the DCL run-time 
system attribute 


o With a Concise Command Language (CCL) command from any 
keyboard monitor, provided the command file is executable and 
includes the DCL run-time system attribute 


o At system start-up time or after a system crash 


Note that you can execute a command file that is resident on disk 
only. However, DCL copies a command file from magnetic tape (DOS 
format only) to a temporary disk file before executing it. For 
example: 


S @MT1:MYFILE.COM 


DCL temporarily copies the command file from magnetic tape to a 
temporary disk file, and then executes it. 


The following sections describe the methods for executing command 
procedures. 


Executing Command Procedures at Login 


When you log in, RSTS/E executes the system-wide command file 
LOGIN.COM, which is located in directory [0,1] on the public 
Structure. This file contains commands defined by the system manager 
that are executed for all users. In addition, the system-wide 
LOGIN.COM file normally contains a command that invokes a private 
LOGIN.COM file located in your account on the public structure. This 
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feature lets you tailor the system for your everyday uSe. 


For example, if you enter the same sequence of commands every time you 
log in, place these commands in a command procedure named LOGIN.COM. 
A typical LOGIN.COM file might contain the following: 


S TYPE SNEWS.TXT 'Display system messages 

S RUN DB1:[2,214]COOKIE.EXE 'Run a program 

S US-ERS:== "SHOW USERS" '‘Abbreviate a command 

S ASSIGN DR3:[2,214] WORK: !Assign a logical name 

S DIR-ECTORY :== DIRECTORY/DATE © tRedefine DIRECTORY command 


Note that if a symbol has one or more abbreviations, DCL displays it 
with an embedded hyphen indicating the minimum abbreviation point. 


If your system manager allows the use of private LOGIN.COM files, the 
System automatically executes these commands every time you log in. 


Executing Command Procedures at Interactive Level 


The @ command executes a command procedure at interactive level. 


Format 
@file-spec [Pl [P2 [... P8]]] 
Prompts 


Command file: file-spec 


Command Parameters 

file-spec 
The file specification of the command file to execute. If you do 
not specify a file type, the system uses .COM. 

PEL P2 byse BOTT 
Optional parameters (one to eight) to pass to the command 
procedure. Separate each parameter with one or more spaces or 


tabs. See Chapter 5 for a complete description of passing 
parameters. 


Introduction 
For example, to execute the command procedure FILST.COM in your 
account on the system disk, enter this command: 
S @FILST 
Figure 1-1 shows how the command procedure is executed at interactive 


level. 


|Command interpreter finds | 
@FILST -------- gy>|FILST.COM in your account | 


|then executes the FILST.COM| 
|commands sequentially... | 


——————--- eo 
<= — 


|and returns control to | 
were et ee eee eee eee |interactive level after | 
|FILST.COM completes | 


Figure l-ls Executing a Command Procedure at Interactive Level 


When you enter the @ command, the command interpreter executes the 
file FILST.COM located in your account on the system disk. Each 
command string in FILST.COM executes sequentially. After reaching the 
end-of-file (EOF) for FILST.COM or after executing an EXIT or STOP 
command, the command interpreter returns control to interactive level 
and displays the $ prompt at your terminal. You can then resume 
interactive work. 


Note 
You can also use the @ command from other keyboard 
monitors. However, you must precede it with the § 
character. For example: 


Ready 


S@FILST 
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When you enter the @ command at the DCL prompt, the DCL command 
interpreter assumes that the the name of a file (with the file type 
-COM) follows it. If you enter the @ command without specifying a 
file, DCL prompts you for the file specification. 


If a command procedure is not in your account on the system disk or 
does not have the file type .COM, give the complete file 
Specification. For example: 


S @DB2:RESET.FIL 


This command executes a command procedure located on DB2:. The 
command procedure file name is RESET.FIL. 


If you execute command procedures frequently, you can define a symbol 


name that you can use in place of the entire command line. For 
example: 
S RESET :== @DB2:RESET.FIL 


This assignment statement defines the symbol name RESET to be 
equivalent to the string "@DB2:RESET.FIL." You can then use this 
symbol as a command name during the current terminal session. 


If you want to use a symbol every time you log in, include the symbol 
definition in your login command file. See Chapter 2 for more 
information about using symbols. 


Executing Command Procedures in Batch Mode 


To execute a command procedure in batch mode, use the SUBMIT command 
followed by the file specification of the procedure. The file type 
defaults to .COM. When you use this method, the batch processor 
executes the command procedure while you continue to work at your 
terminal. You should submit procedures that require lengthy 
processing time for batch processing. 


For example, to execute the command procedure COPY.COM in batch mode, 
enter the command: 


S SUBMIT COPY 


In this example, the command interpreter finds the file COPY.COM in 
your account and submits it to the default batch queue for processing. 
After the batch job is queued, your terminal is free for you to 
continue interactive work. 


See the RSTS/E System User’s Guide and RSTS/E System Manager’s Guide 
for more information on batch processing. 
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Executing Nested Command Procedures 


Executing one command procedure from inside another is called nesting. 
To execute one command procedure from inside another, use the @6 
command followed by the name of the nested procedure. This process is 
Similar to using a CALL statement in a high-level language. 


When the DCL command interpreter finds a nested command procedure, it 
reads input from the second procedure until it reaches the end of the 
File or until the procedure exits. Control then returns to the first 
command procedure at the line following the @ command. 


Note that you can nest a maximum of 13 command procedures on RSTS/E. 
See Chapter 7 for more information about nesting command procedures. 


Executing Command Procedures with the RUN Command 


You can use the RUN command from any keyboard monitor to execute 
command procedures as you would a program on RSTS/E. A command file 
that you execute with the RUN command must follow these rules: 


o The file must be on disk 


o You must set the execute bit (64) in the file’s protection 
code 


o The file must have DCL as its run-time system 


Note that you cannot pass any parameters to command files that you 
execute with RUN. See Chapter 5 for a complete discussion of 
parameter passing. 


Chaining to Command Procedures from a Program 


You can also execute a command procedure using the CHAIN statement or 
the .RUN directive. Command files you chain to must follow the same 
rules as command files you execute using the RUN command. 


To pass parameters when you chain to a command procedure, you must 
specify a nonzero parameter word and load core common with one or more 
parameter values separated by spaces or tabs. See Chapter 5 for more 
information about passing parameters. 
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Executing Command Procedures with CCLs 


The Concise Command Language (CCL) lets you execute command procedures 
that are defined as CCLs by your system manager. 


When you execute a command procedure with a CCL command, you must 
follow the same rules as command files you chain to; that is, to pass 
parameters you must specify a nonzero parameter word and load core 
common with one or more parameter values separated by spaces or tabs. 
For complete information about parameter passing, see Chapter 5. 


See the RSTS/E System Managers Guide for more information about 
defining or using CCLs. 


Command Procedures and System Management 


The RSTS/E system manager can create a system-wide LOGIN.COM file 
containing commands that are executed for all users. If you area 
system manager, you also use command files in these ways: 


o When you start timesharing, the system automatically loads 
DCL and executes the file [0,l1]SYSINI.COM. SYSINI.COM 
performs preliminary startup procedures and then executes 
[0,1]START.COM, passing it the parameter "START" in Pl. 


o When the system restarts after a system crash or power 
failure, it automatically loads DCL and executes the file 
[O0,1]SYSINI.COM. SYSINI.COM then executes [0,1]START.COM, 
passing it the parameter "CRASH" in Pl. 


See the RSTS/E System Manager’s Guide for complete information about 
using command files in system management. 
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Using Symbols in Command Procedures 


This chapter tells you how to define and use symbols in command 
procedures. It describes: 


o The syntax of symbol names 
o How to define symbol values 


o How the command interpreter substitutes values for symbols 
during command processing 


Symbols in DCL 


A symbol is a name that represents a number, character, or logical 
value. You define a symbol in an assignment statement. You use 
symbols in command procedures as constants or variables, and 
manipulate them in much the same way as you manipulate variables ina 
programming language. This capability, combined with the ability to 
control execution flow in command procedures, makes the DCL command 
language very much like a programming language. 


The following example shows how you can define a symbol to represent a 
string: 


S$ FILE = "SOURCE.CBL" 
This assignment statement gives the symbol name FILE the string value 
"SOURCE.CBL". You can then refer to the file SOURCE.CBL symbolically 
by using the symbol name FILE. For example: 


S$ COBOL 'FILE’ 


Using Symbols in Command Procedures 


The apostrophes around the symbol name FILE tell the command 
interpreter that the enclosed word is a symbol name. The command 
interpreter substitutes the string value "SOURCE.CBL" for FILE before 
executing the COBOL command. 


Symbol Names 


A symbol name is a string from 1 to 255 characters long that can 
Consist of: 


Oo Uppercase letters A-Z 
o Lowercase letters a-z 
o Numbers 0-9 

6: Dollar signs: (5) 

o Underscores (_) 


Note that the command interpreter always converts lowercase letters in 
symbol names to uppercase. 


Also note the following restrictions for symbol names: 


o You cannot begin a symbol name with a numeric character, an 
underscore, or the characters FS (reserved for DCL function 
names). 


o Symbols that begin with the $ character are reserved symbols. 
You cannot create or assign new values to reserved symbols. 
You can, however, use a $ character anywhere else within a 
symbol name. 


o In a symbol name, the underscore (_) character is interpreted 


in the same way as any other character. This differs from 
its use with DCL gualifiers, where the underscore is 
transparent. For example, the symbol names MYFILE and 


MY FILE are different symbols. 


o You cannot begin a symbol name with a hyphen (-) character or 
an asterisk (*) character. 


When you create symbol names, you can use the hyphen (-) character or 
the asterisk (*) character to specify an abbreviation point for the 
symbol. Specifying an abbreviation point lets you reference the 
symbol name by any one of its abbreviations in any DCL command that 
allows symbol names. This feature also lets you create command 
synonyms that act like DCL commands. For example, in DCL you can 
specify the PRINT command as PR, PRI, PRIN, or PRINT. Likewise, you 
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can create the symbol: 


S US-ERS = "SHOW USERS" 


You can then refer to the symbol USERS as US, USE, USER, or USERS (in 
command synonym substitution only). 


Note that DCL displays an error message if you: 


O 


O 


Use more than one hyphen or asterisk in a symbol name. 


Create a symbol name with an abbreviation that matches any 
existing abbreviation of another symbol. For example: 


S PR-INT = "PRINT/COPIES=2" 
S PR-OTECT = "SET PROTECTION=60" 


In this example, DCL displays an error message when you make 
the second assignment, because the abbreviations match. 


Symbol Values 


You can assign values to symbols using any of the following methods: 


O 


Assigning symbol names to expressions, constant values, DCL 
functions, or to other variable symbol names with assignment 
statements. 


Passing up to eight parameters to a command procedure when 
you invoke it, or to a batch job when you submit it to a 
batch queue. (Chapter 5 discusses parameter passing. ) 


Using the INQUIRE command to prompt for a symbol’s value. 
(Chapter 5 describes the INQUIRE command. ) 


Using the READ command to read a record from a file and 


assign it as a string value to a specified symbol. (Chapter 
6 describes the READ command. ) 


Note 


RSTS/E restricts the space available for storing 
symbols. Whenever insufficient space (less than 100 
bytes) remains to define a symbol and its value, an 
error message appears. Therefore, you should delete 
symbols you no longer need and avoid excessively long 
symbol names. 
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Symbol Types 


A symbol type can be either string or integer, depending on the value 
Or expression you assign. When you use an expression, DCL evaluates 
it to determine the value to assign to the symbol. If the expression 
evaluates to a string, DCL assigns a string value to the symbol. If 
the expression evaluates to an integer, DCL assigns an integer value 
to the symbol. 


DCL determines the type of expression by the types of values you use 
in the expression and by the type of operations you use to manipulate 
these values. Chapter 3 describes the rules that DCL uses to 
determine an expression’s type. 


The following sections describe how you assign values to symbols. 


Symbol Assignment 


Use an assignment statement to define a symbol and assign it a string 


Or integer value. The format of an asSignment statement is: 
symbol-name =[=] expression 
where: 

symbol-name is a name from 1 to 255 characters long that contains 


the characters listed in the "Symbol Names" section at 
the beginning of this chapter. 


assigns the value you specify and places the symbol 
name and value in the local symbol table. 


assigns the value you specify and places the symbol 
name and value in the global symbol table. 


expression is an integer or string expression. The expression’s 
value is assigned to the symbol name. 


If the symbol name does not exist when you enter the assignment 
statement, then DCL creates the symbol and assigns its value. If the 
symbol name already exists, then DCL assigns the new value, replacing 
the previous value. For example: 


S COUNT = 0 


This assignment statement assigns the value 0 to the local symbol 
COUNT. 


Using Symbols in Command Procedures 


Use double equal signs (==) to assign a symbol to the global symbol 
table. For example: 


S$ NEWCOUNT == 10 


This assignment statement assigns the value 10 to the global symbol 
NEWCOUNT. 


You must enclose string literals in quotation marks ("). For example: 
S TERM == "SET TERMINAL" 

This assignment statement assigns the string value "SET TERMINAL" to 

the global symbol TERM. If DCL finds unmatched quotation marks in a 

command string that you assign to a symbol, it displays an error 


message. 


If you specify an expression that contains other symbols, DCL uses the 
value of those symbols when evaluating the expression. For example: 


S TOTAL = NEWCOUNT + 10 


S SHOW SYMBOL TOTAL 
TOTAL = 20 


In this example, you use an arithmetic assignment statement to assign 
a value to the symbol TOTAL. Note that DCL automatically substitutes 


the value 10 for the symbol NEWCOUNT before evaluating the expression. 
See the section "Symbol Substitution" for further discussion. 


String Assignment 


To assign a string to a symbol, you can use a special string 
assignment statement. The format of a string assignment statement is: 


symbol-name :=[=] string 


where: 


symbol-name is a name from 1 to 255 characters long that contains 
the characters listed in the "Symbol Names" section at 
the beginning of this chapter. 

= assigns the string value you specify and places the 


symbol name and value in the local symbol table. 
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assigns the string value you specify and places the 
symbol name and value in the global symbol table. 


string specifies the string value to assign to the symbol. 
The string can be from 0 to 255 characters long. 


If the symbol name does not exist when you enter the assignment 
statement, then DCL creates the symbol name and assigns its string 
value. If the symbol name already exists, then DCL assigns the new 
string value, replacing the previous value. 


When you use the special string assignment statement, you do not have 
to enclose the string in quotation marks. For example: 


S TEMP_STRING :== error number Li 


This assignment statement assigns the string "ERROR NUMBER 11" to the 
global symbol TEMP STRING. 


Note that DCL performs the following actions when you use the special 
string assignment statement to assign a string not enclosed in 
quotation marks: 

o Converts lowercase characters to uppercase 


o Removes leading and trailing spaces or tabs 


o Reduces multiple spaces or tabs between characters to a 
Single space 


When you enclose the string in quotation marks, DCL does not perform 
case conversion and keeps all spaces and tabs. For example: 


S TEMP_STRING :== "error number i o 


This assignment statement assigns the string "error number 11" to 
the global symbol TEMP_STRING. 


Symbol Tables 


The DCL command interpreter stores symbol names and their associated 
values in two types of symbol tables: 


o A local symbol table, which contains symbols you can use at 
the current command level 


o A global symbol table, which contains symbols you can use at 
all command levels 
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DCL has a separate local symbol table for each command level except 
the interactive level. A command level is the DCL environment from 
which you issue commands. When you nest a command procedure, you 
increase the command level by one. 


For example, when you log in and type commands at your terminal, you 
are issuing commands from command level 0 (the interactive level). If 
you execute a command procedure, the commands in the procedure are 
executed at command level 1. When the procedure terminates and the 
DCL prompt reappears on your screen, you are back at command level 0. 


To create a local symbol, use a single equal sign (=) in the 
assignment statement. For example: 


S TEMP = 1 


When a nested command procedure ends, DCL deletes the local symbol 
table current to that command level and makes current the next higher 
level local symbol table. Because each local symbol table is unique, 
the same symbol can exist in more than one local symbol table. This 
feature lets each command file use symbols that are separately 
defined, thus avoiding conflicts with the use of those symbols 
elsewhere. For example, you can define the local symbol FILE at 
several command levels, to have different values at each command 
level. When the symbol value is needed, DCL first searches the local 
symbol table at the current command level: if no symbol is found, it 
then searches the global symbol table. 


Note that no local symbol table exists at the interactive command 
level. DCL places any symbol that you define at the interactive level 
in the global symbol table, whether you use a single or double equal 
Sign (==) in the assignment statement. 


DCL maintains only one global symbol table, which is recognized at 
every command level including the interactive level. To create a 
global symbol, use a double equal sign in the assignment statement. 
For example: 

S VAL == 45 


The following sections describe how DCL performs symbol substitution. 
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Symbol Substitution 
DCL performs symbol substitution by replacing symbol names in the 
command string with their current values. To use symbols in commands 
and command procedures, you must understand the following mechanics of 
symbol substitution: 

o Command synonym substitution 

oOo Apostrophe substitution operators 

o Automatic evaluation 


o Undefined symbols 


Oo Verification of symbol substitution 


Command Synonyms 
You frequently use global symbols to define command synonyms. 
Normally, you place command synonyms in your LOGIN.COM file to make 
the synonyms available each time you log in. For example: 
S KB == "SET TERMINAL/DEVICE=" 
This assignment defines KB as a new DCL command. You can now type: 
S$ KB vT125 
DCL executes the command as if you typed: 
S$ SET TERMINAL/DEVICE= vT125 
Note that the DCL command interpreter processes a command string by 
examining the first command keyword to determine if it is a defined 
symbol. If it is a defined symbol, DCL automatically substitutes the 
value of the symbol for the symbol name before executing the command 


String: 


You can also use command synonyms to redefine existing DCL commands, 
which lets you change a default qualifier or parameter. For example: 


S PRINT == "PRINT/COPIES=2" 


When you later issue the PRINT command, DCL automatically prints two 
copies of the file you specify. 


You can override automatic command substitution by placing an 
underscore (_) before the first character in the command keyword. 
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Then, even if the keyword is a defined symbol, no automatic 
substitution occurs. For example: 


S$ _PRINT MY.FIL 


This command prints one copy of the file MY.FIL, because the preceding 
underscore tells DCL not to perform automatic substitution. 


Note that you can use symbol name abbreviations in command synonym 
substitution only. 


Apostrophes in Symbol Substitution 


If you use a symbol name in place of a command parameter or qualifier, 
you must enclose it in apostrophes (’...’). When DCL finds a symbol 
name enclosed in apostrophes, it replaces the symbol name with its 
current value. For example: 


S TYPE ’FILENAME’ 


In this example, the string FILENAME is a symbol name used as a 
parameter for the TYPE command. The apostrophes surrounding the 
String tell DCL that FILENAME is a symbol name and not a literal 
string. 


If you want to include a symbol name within a literal string, place 
two apostrophes before the symbol name and one apostrophe after it. 
For example: 


S$ TEXT = "File '’FILENAME’ deleted" 


If the current value of the symbol FILENAME is MYFILE.DAT, then the 
symbol TEXT is given the string value: 


File MYFILE.DAT deleted 


Note that when you use apostrophes to request symbol substitution, DCL 
performs iterative substitution from left to right in the command 
string. This means that for each symbol name found in the command 
line, the string resulting from the substitution is scanned again from 
the beginning to determine whether the string contains any 
apostrophes. 


If there are apostrophes, the command interpreter performs 
substitution and again examines the resulting string for apostrophes. 
For example: 


> FILE g= **7AF* 
S A := FILE1.MEM 
S TYPE 'FILE’ - 
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DCL processes this example as follows: 


1. DCL assigns the symbol name FILE to the string value ’A’. 
The quotation marks prevent DCL from substituting a value for 
’A’ (which you have not yet defined). 


2. DCL assigns the string value FILE1.MEM to the symbol name A. 


3. DCL substitutes the current value of ’/FILE’, when it scans 
the TYPE command string, resulting in: 


TYPE ‘A’ 


4, Because the current value contains apostrophes, DCL scans the 
line again and substitutes the value of ’A’. Finally, DCL 
executes the command string: 


TYPE FILE1.MEM 


When scanning a command string for apostrophe substitution, DCL 
performs a maximum of 100 iterations. If the command string still 
contains apostrophes after 100 iterations, DCL displays an error 
message and does not process the command. 


DCL performs apostrophe substitution both before and after the command 
substitution occurs. For example: 


S$ EXEC := "’COMMAND’" 
$ COMMAND := "DIRECTORY [1,2]" 
S$ QUAL := "/DATE" 


S EXEC 'QUAL’ 


In this example, when DCL processes the command string EXEC 'QUAL,’ it 
first performs apostrophe substitution on ‘QUAL,’ resulting in 

EXEC /DATE. Then command substitution occurs, resulting in 

‘COMMAND’ /DATE. Finally, DCL performs apostrophe substitution again, 
resulting in DIRECTORY [1,2] /DATE. 


Automatic Evaluation 


When DCL evaluates an expression, it assumes that a keyword beginning 
with an alphabetic character is a symbol name. In this case, 
evaluation is automatic and apostrophes are not needed. In fact, if 
you use apostrophes, the results may be quite different because 
iterative substitution occurs. 
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For example, when you use an arithmetic assignment statement, DCL 
automatically evaluates the expression on the right hand side of the 
statement: 


$ TOTAL = COUNT + 1 
Note that you do not need apostrophes to request substitution for the 
symbol COUNT because DCL automatically substitutes values for symbols 
as it executes arithmetic assignments. 
Similarly, no apostrophes are necessary in the following IF command: 


S IF A .EQ. B THEN GOTO NEXT 


In this example, the IF command assumes that both A and B are symbol 
names and uses their current values to test their equality. 


Undefined Symbols 


If a symbol is not defined when you use it in a command string, then 
DCL displays an error message and sets the reserved symbols SSEVERITY 
and SSTATUS to the exit status ERROR. In addition, DCL does not 
process the command that contains the undefined symbol. See Chapter 8 
for more information about SSEVERITY and SSTATUS. 


Verifying Symbol Substitution 

The SET VERIFY and SET NOVERIFY commands control whether DCL displays 
lines in a command procedure as it executes them. Use the SET VERIFY 
command when you want to determine the cause of errors that occur 
within a command procedure. When verification is in effect, DCL 


displays each command line exactly as it appears in the command file, 
before any substitution. 


Format 
SET [NO]VERIFY 
Command Qualifiers Defaults 


/{NO]DEBUG /NODEBUG 
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Command Qualifiers 
/{NO]DEBUG 


Specifies whether DCL enables command debugging. You can use 
this qualifier only with SET VERIFY. When enabled, DCL displays 
each command line twice: once as it appears in the command file, 
and again as it appears after apostrophe and command 
Substitution. The default is /NODEBUG. 


SET NOVERIFY is the default setting. When you use this setting, DCL 
does not display command lines read from a command file. However, DCL 
always displays any error messages that occur. 


When SET VERIFY is in effect, it is global to all command procedures 
and remains in effect until you change it with SET NOVERIFY. Note 
that you can also use the DCL function FSVERIFY to change the current 


verification setting. See Chapter 4 for more information about 
FSVERIFY. 


Displaying Symbols 
The SHOW SYMBOL command lets you display the value of a specified 


symbol or of all symbols in a local symbol table, the global symbol 
table, or both. 


Format 
SHOW SYMBOL [symbol -name] 


| | 
| | 
| | 
| | 
| Command Qualifiers Defaults | 
| | 
| | 
| | 
| | 


/ALL Fae 
/GLOBAL 
JGLOCAL 
tee ee ee ee ee ee ee ee eee + 


Command Parameters 
symbol-name 


The name of the symbol to display. DCL returns an error if the 
symbol is not found. If you do not specify a symbol name, /ALL 
is assumed. If you specify both a symbol name and the /ALL 
qualifier, the symbol name takes precedence. 
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Command Qualifiers 
/ALL 


Tells DCL to display all symbols in the specified symbol table. 
It is the default. 


/ GLOBAL 


Tells DCL to display only global symbols. 


/ LOCAL 


Tells DCL to display only local symbols. 


Within a command file, you can use the /LOCAL or /GLOBAL qualifiers 
with a symbol-name to restrict searching to either the local or global 
symbol table. If you do not specify the /LOCAL or /GLOBAL qualifier, 
DCL searches both tables. If DCL finds a symbol name in both tables, 
it displays the local symbol definition before the global symbol 
definition. Global symbols are always displayed with a double equal 
Sign (==), while local symbols are displayed with a single equal sign 


i =} 

When you are at the interactive command level, you can only display 
global symbols because no local symbol table exists at this level. 
DCL displays an error message if you use the /LOCAL qualifier at this 
level. 


If you want to display a symbol that has an abbreviation point, do not 
specify the hyphen character along with the symbol name. For example: 


S$ SHOW SYMBOL USERS 
US-ERS = "SHOW USERS" 


Note that if a symbol has one or more abbreviations, DCL displays it 
with an embedded hyphen indicating the minimum abbreviation point. 


Other examples of the SHOW SYMBOL command follow: 
S$ SHOW SYMBOL/LOCAL 
This command displays all symbols in the local symbol table. 


S$ SHOW SYMBOL COUNT 
COUNT = 4 


This command displays the local symbol COUNT. Because the value 4 is 
not in quotation marks, the symbol has a numeric value. 
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S$ SHOW SYMBOL PRINT 
PRINT == "PRINT/NOFEED" 


This command displays the global symbol PRINT. Because the value 
"PRINT/NOFEED" is in quotation marks, the symbol has a string value. 


Deleting Symbols 


Use the DELETE/SYMBOL command to delete symbols. You can delete one 
or all local symbols from the local symbol table for the current 
command level or one or all global symbols from the global symbol 
table. 


DELETE/SYMBOL [symbol -name ] 


/ALL 
/GLOBAL 
/LOCAL 


| 
| 
| 
| 
| Command Qualifiers Defaults 
| 
| 
| 
| 


Command Parameters 

symbol -name 
The name of the symbol to delete. DCL returns an error if the 
symbol is not found. If you specify both a symbol name and the 
/ALL qualifier, the symbol name takes precedence. 

Command Qualifiers 


/ALL 


Tells DCL to delete all symbols in the specified symbol table. 


/ GLOBAL 


Tells DCL to delete the global symbol you specify. By default, 
DCL searches the global symbol table when you attempt to delete a 
symbol at the interactive level. 
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/ LOCAL 
Tells DCL to delete the local symbol you specify. By default, 


DCL searches the local symbol table when you attempt to delete a 
symbol at command levels other than the interactive level. 


Note that DCL automatically deletes the symbols in a local symbol 
table whenever the command procedure at that level exits. In 
addition, DCL deletes symbols in the global symbol whenever you log 
Out . 
Remember that because RSTS/E restricts the space available for storing 
local and global symbols, you should always delete symbols that you no 
longer need. 
Examples of the DELETE/SYMBOL command follow: 

S DELETE/SYMBOL/ALL/GLOBAL 


This command deletes all user-defined global symbols. 


S$ DELETE/SYMBOL/LOCAL COUNT 


This command deletes the local symbol COUNT. 


sheenh! 


Chapter 3 


Expressions and Operators 


This chapter describes the types of values and operators you can use 
in expressions. Chapter 2 described how you can equate a symbol to 
either a string or an integer expression. The value that DCL assigns 
to the symbol is the result of the expression. For example: 


$ C = 4 + FSINTEGER("6") - A 
This command assigns a symbol (C) to an expression containing an 
integer (4), a DCL function (FSINTEGER("6")), and a symbol (A). The 
value that DCL assigns to the symbol C is the result of the operations 


in the expression. In this example, the expression evaluates to an 
integer value. 


DCL also lets you use expressions: 
o As DCL function arguments (see Chapter 4) 
o With OPEN, CLOSE, READ, and WRITE commands (see Chapter 6) 


o With IF commands (see Chapter 7) 


Operands in Expressions 


Expressions can contain strings, integers, DCL functions, symbols, or 
combinations of these values. Expressions consist of operands and 
operators. Operands are the values on which to perform an operation. 
Operators specify the operation for DCL to perform in evaluating the 
expression. 
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Strings 


A string can contain any printable characters. When you use strings 
in expressions, you must enclose them in quotation marks. To include 
quotation marks in a string, type two consecutive sets of quotation 
marks. For example: 


S PROMPT = "Type ""YES"" Or a | | @ itil 
S SHOW SYMBOL PROMPT 
PROMPT == "Type "VES" or "nNo"™" 


When you make the symbol assignment, you must use two sets of 
quotation macks around the words YES and NO. Also, you must enclose 
the entire string in quotes because the string is used in an 
expression. Note that DCL preserves uppercase and lowercase, spaces, 
and tabs when you make the symbol assignment in this way. In 
addition, DCL places the symbol in the global symbol table because you 
defined it at the interactive command level. 


You can continue a string over two lines by using a plus sign (+) for 
string concatenation, and a hyphen (-), for continuation. For 
example: 


S MONTHLY = "MONTHLY REPORT --" +- 
Continue: " JUNE 1985" 


S SHOW SYMBOL MONTHLY 
MONTHLY == "MONTHLY REPORT -- JUNE 1985" 


You can also concatenate several symbols to create a long string. For 
example: 


S$ FIRST = "If at first you don’t succeed," 
S$ SECOND = " try, try again." 
$ THIRD = FIRST + SECOND 


S$ SHOW SYMBOL THIRD 
THIRD == "If at first you don’t succeed, try, try again." 


Note that both operands must be strings for string concatenation to 
occur. If either operand to the plus sign (+) operator is an integer, 
then DCL performs addition, not concatenation. 
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Integers 


The DCL command interpreter treats all numeric values as decimal 
integers. The following examples show how to use integers in 
expressions: 


S COUNT = 4+ 1 
S$ DATA = COUNT + l 


S SHOW SYMBOL COUNT 
COUNT == 5 


S SHOW SYMBOL DATA 
DATA == 


In this example, you define two symbols using integer expressions and 
use the SHOW SYMBOL command to display the value of the symbols. 


Note that you do not use quotation marks with integers. 


DCL Functions 


DCL functions let you obtain information about a requested item. You 
invoke a DCL function by typing its name, which always begins with the 
characters FS, and its argument list: 


FSfunction-name(argument[,...]) 


You must enclose the argument list in parentheses. Use DCL functions 
in expressions in the same way you use strings, integers, and symbols. 
The following example uses the FSLENGTH function in an expression. 
(The FSLENGTH function returns an integer that specifies the length of 
a string.) DCL assigns the returned value to the symbol LEN. For 
example: 


S$ LEN = FSLENGTH ("Roses are red and violets are blue.") 


S$ SHOW SYMBOL LEN 
LEN == 35 


Note that you do not enclose DCL functions in quotation marks. In 
addition, you must specify the arguments for DCL functions as 
expressions. Therefore, if an argument contains a string, you must 
enclose the string in quotation marks. If an argument contains an 
integer, a symbol, or another DCL function, do not enclose these 
values in quotation marks. In the previous example, the FSLENGTH 
function is not enclosed in quotation marks; however, the argument (a 
String) is. 


Expressions and Operators 


The value and data type returned by a DCL function depend on the 
function. See Chapter 4 for complete descriptions of each DCL 
function. 


Symbols 


When you use a symbol in an expression, DCL automatically substitutes 
the symbol’s value. For example: 


$ COUNT = 3 
$ NEWCOUNT = COUNT + 1 


$ SHOW SYMBOL NEWCOUNT 
NEWCOUNT == 4 


See Chapter 2 for more information about symbol substitution. 


The following sections describe the conversion of value types in 
expressions; that is, how strings are converted to integers, and how 
integers are converted to strings. 


Value Type Conversion in Expressions 


Expressions can contain both integer and string values as operands, 
which are the values on which to perform an operation. DCL 
automatically converts such expressions to either a string or integer 
type, depending on the types of values used in the expression and on 
the types of operations used to manipulate those values. 


You can use the FSTYPE function to determine an expression’s type. 
You can also perform value conversion explicitly using the FSINTEGER 
and FSSTRING DCL functions. See Chapter 4 for more information on 
these functions. 


Table 3-1 lists the rules that DCL uses to determine an expression’s 
type. 
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Table 3-1: Rules for Determining Expression Types 


Se tor ere re ee ee ee ee ee eee + 
| Expression | Type | 
Se torr rr ee ee ee eee ee eee + 
| | | 
| Integer value | Integer | 
| | | 
| String value | String | 
| | | 
| Integer DCL function | Integer | 
| | | 
| String DCL function | String | 
| | | 
| Integer symbol | Integer | 
| | | 
| String symbol | String | 
| | | 
| +, -, or .NOT. Any value | Integer | 
| | | 
| Any value .AND. or .OR. Any value | Integer | 
| | | 
| Any value +, -, *, or / Any value | Integer | 
| | | 
| String + String | String | 
| | | 
| Any value (string comparison) Any value | Integer | 
| | | 
| Any value (integer comparison) Any value | Integer | 
Se Sl + 


Note that DCL automatically converts the expression to either a string 
Or integer type before performing further operations. 
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Converting Strings to Integers 

DCL converts numeric strings, which consist of the numbers 0 through 
9, optionally preceded by one or more plus (+) or minus (-) 
characters, to their signed 32-bit values. 


DCL converts alphabetic strings according to these rules: 


o Strings that begin with the letter T, t, or Y, y, are 
converted to the value 1 (true). 


o All other strings are converted to the value 0 (false). 


For example: 


String -- - > Integer 
"4789" - - - > 4789 

ne ot ae | 

"ves" - - - > 1 (true) 
"PILE" ae 0 (false) 


Converting Integers to Strings 


DCL converts integers to strings by generating a string consisting of 
the decimal numbers of the integer. If the integer is negative, then 
the minus sign (-) character precedes the numeric characters. Note 
that DCL suppresses leading zeros. For example: 


Integer -- - String 
1000 -- - "L000" 
- 47 -- ".47" 
0 = 2 a 6 uy 
007 --- at ee 
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Operators in Expressions 


Use the operators shown in Table 3-2 to form an expression and define 
the order of evaluation priority. Logical and comparison operators 
must be preceded by a period (.) with no intervening blanks. You must 
terminate an operator with a period. You can type any number of 
blanks or tabs between operators and operands. For example, the 
following expressions are equivalent: 


Xs BOS.Y 
x. «.BOS. ¥ 


When you specify more than one operation in an expression, DCL 
performs the operations in the order of priority listed in Table 3-2, 
where 1 is the highest priority (performed first) and 6 is the lowest 
(performed last). (For example, multiplication is performed before 
addition.) You can use parentheses to override the order in which 
operators are evaluated, because expressions within parentheses are 
evaluated first. 


Table 3-2 lists the valid operators in expressions. Operators of the 


same priority are performed from left to right, as they appear in the 
command. 
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Table 3-2: 


Arithmetic 
Operators 


| String 
| Operator 


| 

| Logical 

| Operators 
| 


Arithmetic 
Comparison 
Operators 


| 

| String 

| Comparison 
| Operators 
| 

| 

| 

| 


Summary of Operators in Expressions 


Arithmetic 
Arithmetic 
Arithmetic 
Arithmetic 
Arithmetic sum 

Arithmetic difference 


unary plus 
unary minus 
product 
division 


Logical Complement 
Logical AND 
Logical OR 


Arithmetic equal to 
Arithmetic greater than or 
equal to 

Arithmetic greater than 


Arithmetic 
to 
Arithmetic less than 
Arithmetic not equal to 


less than or equal 


String equal to 

String greater than or equal 
to 

String greater than 

String less than or equal to 
String less than 

String not equal to 
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Arithmetic Operations 


Use arithmetic operations to perform calculations on integer 
expressions. The result of an arithmetic operation is an integer. 
Operands in arithmetic operations are integer expressions. If you 
specify a string value as an operand, DCL converts it to an integer 
value before performing the operation. 


Note that DCL uses the plus sign (+) character for both the arithmetic 
Sum operator and the string concatenation operator. DCL performs 
addition whenever one or both of the operands is an integer. However, 
if both operands are strings, then DCL performs string concatenation. 


Examples of arithmetic operations follow: 


Expression Value of Symbol 
A= 5+ 10 / 2 A = 10 

B=5* 3 -4* 6 Sf 2 B = 3 

Coe .5 2. (6 = 2) 2 8 7 221) C = 2 


Logical Operations 


Use logical operators to perform logical functions on integer values. 
The result of a logical operation is an integer. 


Operands for logical operations are integer expressions. If you 
Specify a string value as an operand, DCL converts it to an integer 
value before performing the operation. 


Examples of logical operations follow: 


Expression Value of Symbol 
A = 3 .OR. 5 A= 7 
B = 3 .AND. 5 B= 1 
C = .NOT.3 C= -4 
D= 3 + 4 .AND. 2 + 4 D = 6 


Expressions and Operators 


Arithmetic Comparisons 


Use arithmetic comparison operators to compare integer values. If the 
result of an arithmetic comparison is true, the expression has the 
value 1. If the result of the comparison is false, the expression has 
the value 0. 


If you specify a string value as an operand, DCL converts it to an 
integer before performing the comparison. If a string begins with an 
uppercase or lowercase T or Y, DCL converts it to the integer 1. If 
the string begins with any other letter, DCL converts it to the 
integer Q. 


Examples of arithmetic comparisons follow: 


Expression Value of Expression 


I. #bBs 2 1 (true) 
1 26Ps 2 0 (false) 
1+ 3 .EQ. 2 + 5 0 (false) 
"TRUE" .EQ. 1 1 (true) 
"FALSE" .EQ. 0 1 (true) 
2S eos 123 1 (true) 


String Comparisons 


Use string comparison operators to compare strings. DCL compares 
Character strings based on the binary values of the characters in the 
String. If the result of the string comparison is true, the 
expression has the value 1. If the result of the comparison is false, 
the expression has the value 0. 


If you specify an integer value as an operand in a string comparison, 
DCL converts the integer to a string before performing the comparison. 
In addition, if one string is longer than the other, DCL pads the 
Shorter string with null characters to match the length of the longer 
String before making the comparison. 
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Examples of string comparisons follow: 


Expression Value of Expression 
"ABCD" .LTS. "EFG" 1 (true) 
"YES" .GTS. "YESS" 0 (false) 
"PALSE" .EQS. 0 0 (false) 


String Concatenation 


Use a plus sign character (+) between strings to link or concatenate 
strings. The result of this operation is a string value. When you 
Specify an integer value as an argument to the plus sign (+) operator, 
DCL performs addition, not concatenation. The following example 
concatenates two strings to form a single string: 


SA = "MYFILE" + ".MEM" 


S SHOW SYMBOL A 
A == "MYFILE.MEM" 
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DCL Functions in Command Procedures 


This chapter describes how to use DCL functions to manipulate strings 
Or integers, or return information about a file, a job, or the system. 
You can use DCL functions in the same places you use symbols, 
expressions, or literal values. In command procedures, you can use 
DCL functions to perform operations such as: 

o Translate logical names 

O Manipulate strings 


o Determine the current processing mode of the procedure 


Format of DCL Functions 
The general format of a DCL function is: 
FSfunction-name([arg,...]) 
where: 
FS indicates a DCL function. 


function-name is the function to be evaluated. You can truncate 
function names to any unique abbreviation. 


( ) enclose function arguments. Functions that have no 
arguments do not need parentheses. 


arQ, +... specify arguments for the function, if any. 


Function arguments can consist of symbols, integer expressions, string 
expressions, or other DCL functions. 
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DCL performs automatic symbol substitution on all function arguments. 
Therefore, when you use a symbol name as a DCL function argument, do 
not enclose the symbol name within apostrophes. 


Note that in some cases, one or more of a function’s arguments are 
optional. If an argument is optional, you can exclude it from the 
argument list. You can also use commas to indicate which argument you 
are excluding from the list. For example, the FSPARSE function has 
three arguments defined, all of which are optional. You can specify 
the first argument, as follows: 


FSPARSE(ARG1) 
In this example, you do not specify the second and third arguments. 
You could also use commas to indicate that you are excluding the 
second and third arguments: 


FSPARSE(ARG1,,) 


If you want to specify the first and second arguments, but omit the 
third, you can use either: 


FSPARSE(ARG1,ARG2) 
Or 
FSPARSE(ARG1,ARG2, ) 


If you want to specify the first and third arguments, but omit the 
second, you must use commas to separate the arguments. For example: 


FSPARSE(ARG1, ,ARG3) 
Note that, in some cases, specifying an argument as a null string or 


as the integer zero is not the same as excluding the argument from an 
argument list. 


DCL Functions 


Table 4-1 summarizes the DCL functions. The rest of this chapter 
describes DCL functions in greater detail and gives examples of their 
use. 
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Table 4-1: Summary of DCL Functions 


Sr per rr ee ee ee ee ee ee ee ee ee eee + 
| Function | Description | 
Sr Sl +: 
| | | 
| FSACCESS | Returns the current job’s access mode | 
t--- eee ee ee eee Her ee ee ee ee ee ee ee ee ee ee eee eee + 
| | | 
| FSASCII | Converts the first character ina string to its | 
| | ASCII value | 
5 Se i + 
| | | 
| FSCHR | Converts an integer to its ASCII value | 
| Hen ee ee ee ee ee ee ee ee ee eee + 
| | 

| FSCVTIME | Converts a date/time string to a string suitable | 
| | for comparisons | 
| frre ee ee ee ee ee ee eee eee “ 
| | | 
| FSEDIT | Edits a string | 
: Se +: 
| | | 
| FSINSTR | Returns the location of a substring | 
5 pont ee ee ee ee ee eee eee ee ee ee ee ee eee + 
| | | 
| FSINTEGER | Converts a string to an integer | 
terre ee eee eee Herr ee ee ee ee ee ee ee ee ee + 
| | | 
| FSJOB | Returns the current job number | 
Se Se “ 
| | | 
| FSLEFT | Extracts a substring from a string, beginning at | 
| | position 1, and ending at the position you specify | 
Se Se ee ee + 
| | | 
| FSLENGTH | Returns the length of a string | 
tree cee eee eee Herr ee ee ee ee ee ee eee + 
| | | 
| FSMESSAGE | Returns the message text associated with a RSTS/E | 
| | error number | 
Hee eee ee eee eee fer ee ee ee ee eee + 
| | | 
| FSMID | Extracts a substring from a string beginning at the | 
| | position you specify | 
Se Se +- 
| | | 
| FSNODE | Returns the current node name | 
Sr Se ee -: 
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Table 4-l: Summary of DCL Functions (Cont.) 


Sr pene ee ee ee ee ee ee ee ee ee eee 
| Function | Description 

Hore eee ee ee eee pr ee ee ee ee eee ee eee ee 
| | 

| FSPARSE | Returns a complete RSTS/E file specification or a 
| | specified field within the file specification 

5 Pr ee ee ee ee ee ee ee ee ee ee eee 
| | | 

| FSPRIVILEGE | Returns the status of a job’s privileges 
Sr pr ee ee ee ee ee ee ee ee ee ee eee 
| | 

| FSRIGHT | Extracts a substring from a string, beginning at 
| | the position you specify, and ending at the 
| | rightmost position of the string 

Se Si i a ea 
| | 

| FSSEARCH | Searches a disk directory for a file and returns 
| | the complete RSTS/E file specification of the next 
| | occurrence of the file 

Se Se a i 
| | 

| FSSTRING | Converts an integer to a string 

Sr Pr ee ee ee ee ee ee ee ee ee eee ee eee 
| | 

| FSTERMINAL | Returns the KB number for the current RSTS/E job 

fore eee ee ee eee pe ee ee ee ee ee ee ee ee ee eee 
| | 

| FSTIME | Returns the current time and date 

Sr pr ee ee ee ee ee ee ee ee ee ee eee 
| | 

| FSTYPE | Returns a string indicating the type of a symbol or 
| | expression 

Sr per ee ee ee ee ee ee ee ee eee 
| | 

| FSUSER | Returns the project-programmer number for the 
| | current RSTS/E job 

| free ee ee ee ee ee ee ee ee ee ee ee ee eee 
| | 

| FSVERIFY | Enables or disables the verification setting 

forte eee eee eee pe ee ee ee ee ee eee 


The following sections describe the DCL functions in alphabetical 
order. 
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FSACCESS 


The FSACCESS function returns a string that shows the current job’s 
execution mode. 


The format of the FSACCESS function is: 
FSACCESS() 


The FSACCESS function returns one of the following keyword strings: 


Keyword 7 Meaning 

BATCH The job is running on a pseudo keyboard, under the 
control of a batch processor. . 

DIALUP The job is running over a dial-up line. 

LOCAL The job is running at a local terminal. 

NETWORK The job was created over the network, and is “winiie 


on a pseudo keyboard under control of the job on the 
remote system. 


SERVER The job is running detached under the control of a 
network controller. 


Use the FSACCESS function in command procedures that must act 
differently depending on the current job’s access mode. 


The following example uses the FSACCESS function: 


S !Exit unless in BATCH mode 
S IF FSACCESS .NES. "BATCH" THEN EXIT 


In this example, the IF command compares the character string returned 
by FSACCESS with the character string BATCH. If the strings are 
equal, processing continues. When the strings are not equal, the 
procedure exits. 
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FSASCII 

The FSASCII function converts the first character ina string to its 
ASCII value. This function is similar to the BASIC-PLUS ASCII 
function. 

The format of the FSASCII function is: 

FSASCII(string) 

where string is a string expression. 

The FSASCII function always returns an integer in the range 0 to 255. 
If you pass a null string as an argument to this function, it returns 
the value 0. If you pass an integer as an argument to this function, 
DCL converts the integer to a string and returns the first character 


of the string. 


The following example uses the FSASCII function: 


S INQUIRE ANSWER "Type Y to continue" 

S CHAR = FSASCII(ANSWER) thy 

S !Check for 'Y’ or ‘'y’ as the first character 

S IF (CHAR .EQ.. 89) .OR. (CHAR .EQ. 121) THEN GOTO CONTINUE 
S EXIT SL 2 

S 


CONTINUE: 


This command procedure uses an INQUIRE command to request user input, 
which is assigned to the symbol ANSWER. The next assignment statement 
uses the FSASCII function to convert the first character of the input 
string to its ASCII value and assigns that value to the symbol CHAR. 
The IF command then tests the first character of the string and 
branches to the label CONTINUE if the first character is Y or y. If 
the string begins with any other character, the procedure exits. 
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FSCHR 


The FSCHR function converts an integer to its ASCII value. This 
Function is similar to the BASIC-PLUS CHRS function. See Appendix D 
for a table of the ASCII character codes and their decimal and octal 
values. 


The format of the FSCHR function is: 
FSCHR( integer ) 


where integer is an integer value that corresponds to the character to 
be returned. 


Use this function to assign the ASCII value of a nonprinting character 
to a symbol. DCL treats all arguments as eight-bit unsigned integers 
in the range 0 to 255. If you specify an integer outside this range, 
the low byte is returned as the ASCII character. For example, 
FSCHR(257) is equivalent to FSCHR(1), and FSCHR(-1) is equivalent to 
FSCHR(255). 


The following example uses the FSCHR function: 


!Define the standard report heading 
FORM FEED = FSCHR(12) 

HEADING = "INTEROFFICE MEMORANDUM" 
NEW _LINE = FSCHR(13) + FSCHR(10) 
INDENT = FSCHR(9) 


in Hn YN YN 


'Write out the report heading 
WRITE/NODELIMITER 1 FORM_FEED , HEADING , NEW_LINE , INDENT 


if If 


This example: 


o Assigns the ASCII character 12 to the symbol FORM_FEED 
indicating a form feed. 


o Assigns the string "INTEROFFICE MEMORANDUM" to the symbol 
HEADING. 


o Assigns the ASCII characters 13 and 10 to the symbol NEW_LINE 
indicating a carriage return and line feed. 
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o Assigns the ASCII character 9 to the symbol INDENT indicating 
a horizontal tab. 


o Uses the WRITE command along with the symbols to format a 
report heading. 


Note that because you specified /NODELIMITER, the next write 
to channel 1 will be indented to the first tab stop. 
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FSCVTIME 


The FSCVTIME function converts a standard DCL date/time string or the 
date/time string returned by the FSTIME function to a date/time string 
of the form: 


yy.-mm.dd hh:mm 

You can use the resultant string to compare two dates. 
The format of the FSCVTIME function is: 

FSCVTIME( [date/time] ) 

where: 


date/time is the date and time to be converted. If you do not 
Supply a date and time, then the current date/time is 
returned. DCL displays an error message if you 
Specify an illegal date/time argument. 


The date/time string can be any valid DCL date/time string, including 
relative dates/times. This function also accepts a string consisting 
of a date field, one or more spaces or tabs, and a time field, which 
lets you convert a string returned by the FSTIME function. 


The function always returns a date/time string that is 14 characters 
long, with a single space between the date and time fields. In 
addition, the time field is always returned in 24-hour format, 
beginning at position 10 in the string. 


The following example converts a system date/time string to a 
comparison string: 


S TIME = FSTIME 
S$ SHOW SYMBOL TIME 
TIME = "01-May-85 03:37 PM" 


S TIME = FSCVTIME(TIME) 
S SHOW SYMBOL TIME 
TIME = "85.05.01 15:37" 


S$ TIME = FSCVTIME("+6DAYS") 
S SHOW SYMBOL TIME 
TIME = "85.05.07 15:37" 


In this example, the FSTIME function assigns the current date/time 
string to the symbol TIME. Then the FSCVTIME function converts the 
date/time string to a string that you can use for comparisons. The 
example also shows that you can specify relative dates/times with this 
function. 
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The FSEDIT function edits a string. This function is similar to the 
BASIC-PLUS CVTS$ function. 


The format of the FSEDIT function is: 


FSEDIT(string,integer ) 


where: 
String is the string to edit. 
integer is a bit-coded value that specifies the editing 


function (or functions) to perform. 


You can use FSEDIT to edit two strings before performing a comparison 
of those strings. For example, you can convert strings to uppercase, 
strip off leading or trailing spaces and tabs, and so forth. After 
you execute this function, DCL returns an edited string. Note that 
you can supply an integer argument, which is the sum of individual 
function values. For example, the value 48 performs both edit 
functions 16 and 32. 


The following example uses the FSEDIT function: 
INQUIRE COMMAND "Command" 


S 
S !Strip spaces/tabs and convert to uppercase 
S$ COMMAND = FSEDIT(COMMAND, 2+32) 


In this example, the INQUIRE command prompts the user for a string to 
edit. After the user enters the string, the FSEDIT function removes 
any spaces or tabs and converts the string to uppercase characters. 


Table 4-2 lists the values for the FSEDIT function. 
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FSEDIT 
Table 4-2: Summary of FSEDIT Functions 
+------- Hr re ee ee ee ee ee ee re ee ee eee 4 
| Value | Editing Function | 
t--- eee Hen ee ee ee ee ee ee eee + 
| | | 
| 2 | Discards all spaces and tabs | 
+------- Her ee ee ee ee re ee ee eee + 
| | | 
| 4 | Discards any of the following characters: | 
| | o Null (ASCII code 0) | 
| | o Line feed (ASCII code 10) | 
| | o Form feed (ASCII code 12) | 
| | o Carriage return (ASCII code 13) | 
| | Oo Escape (ASCII code 27) | 
| | o Delete (ASCII code 127) | 
+---+---- +t------- ee ee ee ee ee ee ee ee ee ee ee ee ee ee eee + 
| | | 
| 8 | Discards leading spaces and tabs | 
t------- Her ee ee ee ee ee eee 
| | | 
| 16 | Converts multiple spaces and tabs to a single space | 
+------- Her re ee ee ee ee ee ee ee + 
| | | 
| 32 | Converts lowercase characters to uppercase | 
+--+ -+-- Hr ee ee ee ee ee ee eee eee “ 
| | | 
| 64 | Converts left and right square brackets ([]) to left and | 
| | vight parentheses (()) | 
tect cee Se ee + 
| | | 
| 128 | Discards trailing spaces and tabs | 
+--+ -+-- Se ee oe ee os 
| | | 
| 256 | Disables editing of characters within quotation marks | 
+------- Hr re ee ee ee ee ee ee eee - 


DCL Functions in Command Procedures 

FSINSTR 
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The FSINSTR function locates a substring within a string and returns 
the position of the substring as an integer. This function is similar 
to the BASIC-PLUS INSTR function. 


The format of the FSINSTR function is: 


FSINSTR(position,string,substring) 


where: 

position is an integer, expression, or symbol that indicates 
the position in the string at which to begin searching 
for the substring. If the position is negative or 0, 
then the string is searched starting at position l. 
If the position argument is greater than the length of 
the string, the function returns the value 0. 

String is the string to search. 

substring is the substring to locate. If the substring argument 


is null, and the position argument is not greater than 
the length of the string, the function returns the 
specified start position. If the substring is not 
located, the function returns the value 0. 


You can specify the string and substring as either a string 
expression, Or as a symbol equated to a string expression. 


The following example uses the FSINSTR function to count the number of 
Spaces ina string: 


S SPACES = 0 

S POS = 0 

S INQUIRE STRING "String" 

S LOOP: 

S POS = FSINSTR(POS + 1,STRING," ") 

S IF POS .EQ. 0 THEN GOTO END 

S SPACES = SPACES + 1 

S GOTO LOOP 

S END: 

S WRITE 0 "Number of spaces = ",SPACES 


This example uses an INQUIRE command to prompt for a string value. 
The first time DCL executes the loop, POS is equal to 1, and STRING is 
equal to 0. After DCL locates a space, it assigns a new value to POS, 
which is the integer position of the space within the string. In 
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addition, each time DCL locates a space, it increments SPACE by 1. 
Finally, after DCL locates all spaces, the procedure branches to the 
label END, and the WRITE command displays a message indicating the 
number of spaces in the string. 
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FSINTEGER 

The FSINTEGER function converts a string expression to an integer. 
The format of the FSINTEGER function is: 

FSINTEGER(string) 

where string is a string expression or symbol. 

Use the FSINTEGER function to set a symbol to an integer value and 


then use the symbol in an operation that requires an integer value. 
For example: 


S A aR 

$ B = FSINTEGER("-9" + A) 
S$ SHOW SYMBOL B 

B= -923 


In this example, the FSINTEGER function returns the integer equivalent 
of the expression ("-9" + A), which evaluates to the character string 
"-923". Because the expression contains two character strings, use 
the plus sign (+) character for concatenation. The FSINTEGER function 
ignores leading and trailing blank spaces. Note that the symbol A was 
assigned the numeric character string "23". 
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FSJOB 

The FSJOB function returns the current job number as an integer. 
The format of the FSJOB function is: 

FSJOB() 


Use the FSJOB function in command procedures that use their own job 
number as input to a task, or that need to extract job information 
From a file, such as a SYSTAT listing. For example: 


$ JOB NO = FSJOB 
S WRITE 0 "This is job number '’JOB_NO’." 


This command procedure assigns the current job number to the symbol 
JOB_NO and then displays the job number on your terminal. 


Note 


Be careful using the FSJOB function in command 
procedures that contain programs that are meant to 
detach during the procedure’s execution. RSTS/E 
creates a new job (containing the same command 
procedure) when the program detaches. Therefore, the 
FSJOB function will return the new job number. 
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FSLEFT 

The FSLEFT function extracts a substring from a string, starting at 
position 1 and ending at the position you specify. This function is 
Similar to the BASIC-PLUS LEFT function. 


The format of the FSLEFT function is: 


FSLEFT(string,position) 


where: 
string is the string from which to extract the substring. 
position is an integer that specifies the ending position of 


the substring to extract. If the position argument is 
negative or 0, the function returns a null string. If 
the position argument is greater than the length of 
the string, the function returns the entire string. 


The FSLEFT function returns a string that consists of all characters 
from the first or leftmost position in the string through the position 
you specify. For example: 


S$ CHARS = FSLEFT("ABCDEFGHI",6) 
S$ SHOW SYMBOL CHARS 
CHARS = "ABCDEF" 


In this example, the FSLEFT function returns the string starting at 
position 1 and ending at position 6. DCL then assigns the resultant 
substring, "ABCDEF", to the symbol CHARS. 
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FSLENGTH 


The 


FSLENGTH function returns the length of the string that you 


specify. This function is similar to the BASIC-PLUS LEN function. 


The 


format of the FSLENGTH function is: 


FSLENGTH(string) 


where string is a string expression or a symbol that equates to a 
string expression. 


The 


Nin I 


$ 


following example uses the FSLENGTH function: 


MSG_NO=5 

MESSAGE = FSMESSAGE(MSG_NO) 

MSG_LEN = FSLENGTH( MESSAGE) 

IF MSG LEN .EQ. 0 THEN GOTO NULMSG 


NULMSG: 


In this example, the FSLENGTH function determines if message text was 
returned by the FSMESSAGE function. If no message was returned, then 


the 


procedure branches to the NULMSG label. 
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The FSMESSAGE function returns message text corresponding to a RSTS/E 
error number. 


The format of the FSMESSAGE function is: 

FSMESSAGE(error number) 

where error number is an integer expression resulting in a value from 
0 to 255. DCL returns a null string if you specify a number that is 


not within this range. 


Use FSMESSAGE in command procedures that display either error message 
text or the system installation name (error number 0). For example: 


S !Get the error message 
S ERROR_TEXT = FSMESSAGE(2) 


After you make this assignment, the symbol ERROR_TEXT has the string 
value: 


?Illegal file name 


Although each error message in the system error message file has a 
numeric value, many numeric values do not have corresponding error 
messages. See Appendix C for a complete list of the numeric values 
associated with RSTS/E error messages. 


FSMID 
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The FSMID function extracts a substring from a string, starting at the 
position you specify. This function is similar to the BASIC-PLUS MID 


function. 


The format of the FSMID function is: 


FSMID(string,position,length) 


where: 
string 


position 


length 


is the string from which to extract the substring. 


is an integer that specifies the starting position of 
the substring. If the position argument is negative 
or 0, the starting position is 1. If the position 
argument is greater than the length of the string, the 
function returns a null string. © 


is an integer that specifies the length of the 
substring to extract. If the length argument is 
negative or Q, the function returns a null string. 


The following example uses the FSMID function: 


S DEF = 


FSMID("ABCDEFGHI",4,3) 


S$ SHOW SYMBOL DEF 


DEF = "DEF" 


In this example, 
position 4. 


the FSMID function returns a string starting at 


The resultant substring, "DEF", is 3 characters long. 
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FSNODE 


The FSNODE function returns the node name of the system on which the 
job 1s running. 


The format of the FSNODE function is: 
FSNODE( ) 


If DECnet/E is installed and enabled on the system, DCL returns the 
node name followed by two colons (::). If DECnet/E is not installed, 
or is not enabled, then DCL returns a null string. For example: 


S$ NODE_NAME = FSNODE 
S IF FSLENGTH(NODE_NAME) .GT. 0 THEN - 
WRITE 0 "Your node is ’’NODE_NAME’" 


In this example, if the job is running on an active DECnet/E node, DCL 
assigns the node name to the symbol NODE NAME. The FSLENGTH function 
compares the length of the string to 0 to determine if a node name was 
returned. If so, the WRITE command displays the node name at your 
terminal. 


FSPARSE 
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The FSPARSE function returns one of three values: 


o A full RSTS/E file specification for the file you specify 


o A specified field within the file specification, when you 
include a field keyword 


o A 32-bit number containing information about the file 
specification 


This function is similar to the BASIC-PLUS File Name String Scan 
System function call. See the RSTS/E Programming Manual for a 


description. 


The format of the FSPARSE function is: 


FSPARSE([file-spec][,default-spec][,field] ) 


where: 


file-spec 


default-spec 


field 


is a string expression that specifies the name of the 
file to be returned. If any part of the file-spec is 
invalid, DCL returns an error. However, if you 
include the FLAGS keyword, DCL returns the value -l. 
If you omit the file-spec or supply a null string, DCL 
uses the entire default-spec. 


is a second file specification that defines defaults 
for any missing fields in the file-spec string. If 
you omit a field in the file-spec string, DCL returns 
the corresponding field in the default-spec string. 
If you omit a field in both the file-spec and the 
default-spec strings, the corresponding field in the 
returned string is null. If both strings are null, 
DCL returns a null string. DCL returns an error if 
any part of the default-spec is invalid. 


is an optional keyword string that returns a specific 
portion of the file-spec. If you do not specify this 
argument, FSPARSE returns a complete filespec, based 
on the other two arguments. The valid field keywords 
are: 


Oo DEVICE -- Returns the device name. The device 
name can be either a physical or logical device 
name. When you specify a physical device name, 
DCL returns the device name preceded by an 
underscore (_). When you specify a logical device 
name, DCL returns the associated physical device 
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FSPARSE 


name preceded by an underscore. However, if the 
logical name is not found, DCL returns the logical 
name with no leading underscore. DCL returns all 
device names followed by a single colon (:). Note 
that if you specify a file-spec without a device, 
DCL returns a null string. 


PPN -- Returns the project-programmer number 
(PPN), in the form [proj,prog]. You can specify 
the asterisk (*) wildcard character in either 
field of the PPN. I£f you specify a file-spec 
without a PPN, DCL returns a null string. 


NAME -- Returns the file name. If the file name 
field consists of six or more question marks 
(222???) or an asterisk (*), DCL returns an 
asterisk (*). If you specify a file-spec without 
a file name, DCL returns a null string. 


TYPE -- Returns the file type, preceded by a 
period (.). If the file type field consists of 
three or more question marks (.???) or an asterisk 
(.*), DCL returns an asterisk preceded by a period 
(.*). If you specify a file-spec without a file 
type, DCL returns a null string. 


STATUS -- Returns the device status word value as 
a 32-bit integer, which contains information about 
the device returned by the FSPARSE function. If 
you specify a file-spec without a device, DCL 
returns the value 0. You can test each bit to 
determine status. The status word corresponds to 
the BASIC-PLUS STATUS variable. 


Table 4-3 shows the information, the tests, and 
the meaning of each bit. 


FLAGS -- Returns the flag word value as a 32-bit 
integer, which contains information about the file 
Specification returned by the FSPARSE function. 
You can test each bit to determine information 
about elements found in the file specification. 
Note that if you specify a null file-spec, DCL 
returns the value 0, which indicates that no file 
Specification was found. In addition, if you 
supply an invalid file-spec and include this 
keyword, DCL returns the value -l. Thus, anytime 
you request FLAGS, you must first check to see if 
the value returned is -l. If it is, then the 
file-spec is invalid, and the other bits are 
meaningless. Use FLAGS when you want to check for 
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Table 4-3: 
terete ee + 
| Bait | 
torr r cee + 
| | 
| O-7F | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| 8 | 
| | 
| | 
| | 
| | 
| 9 | 
| | 
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an invalid file-spec without having DCL display an 
error message. The flag word corresponds to "flag 


word 2" in the BASIC-PLUS file name string scan 


system function call. 


Table 4-4 shows the information, the tests, and 


the meaning of each bit. 


Status Word Values 


(STATUS 


(STATUS 


(STATUS 


sAND.. 255) 


The first eight bits of the 


word contain the handler 


index. 


The following values 


apply for various devices: 


2 
4 
6 


-AND. 256).NE.0 


or 18 a 
device. 


-AND. 512).NE.0 


0 Disk 


Terminal 

DECtape 

Line Printer 
Paper Tape Reader 
Paper Tape Punch 
Card Reader 
Magnetic Tape 

PK: device (pseudo 
keyboard) 

DX: device (flexible 
diskette) 

RJ: device (2780 
remote job entry) 
NL: null device 
DMC11/DMR11/DDCMP 
Interface 
Auto-Dialer 

X-Y Plotter 
Reserved 

KMC1ll 

IBM Interconnect 
DMP11/DMVv11 


The device is open for 
non-file-structured processing 


non-file-structured 


The job does not have read 


access to the device. 
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Table 4-3: Status Word Values (Cont. ) 


(STATUS .AND. 1024).NE.0 The job does not have write 


access to the device. 
11 The device maintains its own 
horizontal position. Such 
devices are keyboards and line 
printers. 


(STATUS .AND. 2048) .NE.0 


| 

| 

| 

| 

| 

| 

| 

EZ (STATUS .AND. 4096).NE.0 | The device accepts modifiers. 
| Such devices use the record 

| number as a modifier word 

| rather than the physical 

| position of the device. 

| Keyboards, line printers, and 
| card readers are such devices. 
| 

13 | 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 


(STATUS .AND. 8192) .NE.0 Device is a character device. 


14 Device is an interactive 


device (keyboard). 


(STATUS .AND. 16384) .NE.0 


5 Device 1S a random-access 
blocked device, such as disk 
and non-file-structured 


DECtape. 


(STATUS .AND. 32768).NE.0 


Reserved; returned as Q. 
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Table 4-4 shows the information, the tests, and the meaning of each 
bit. 


Table 4-4: Flag Word Values 


File name was found in the 
String. 

(FLAGS .AND. 1).EQ.0 No file name was found (and 
bits 1 and 2 of this word are 


(FLAGS .AND. 32).EQ.0 File type was not an * 


character. 


| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | also 0). | 
| | | | 
| 1 | (FLAGS .AND. 2).NE.0 | File name was an asterisk (*) | 
| | | character. | 
| | | | | 
| | (FLAGS .AND. 2).EQ.0 | File name was not an * | 
| | | character. | 
| | | | 
| 2 | (FLAGS .AND. 4).NE.0 | File name contained at least | 
| | | one question mark (?) | 
| | | character. | 
| | | | 
| | (FLAGS .AND. 4).EQ.0 | File name did not contain any | 
| | | ? characters. | 
| | | | 
| 3 | (FLAGS .AND. 8).NE.0 | A period (.) was found. | 
| | | | 
| | (FLAGS .AND. 8).EQ.0 | No period was found, implying | 
| | | that no file type was | 
| | | specified (and bits 4, 5, and | 
| | | 6 of this word are also 0). | 
| | | | 
| 4 | (FLAGS .AND. 16) .NE.0 | A file type was found (that | 
| | | is, the field after the period | 
| | | was not null). | 
| | | | 
| | (FLAGS .AND. 16).EQ.0 | No file type was found. (The | 
| | | field after the period was | 
| | | null -- and bits 5 and 6 of | 
| | | this word are also 0.) | 
| | | | 
| 5 | (FLAGS .AND. 32) .NE.0 | File type was an * character. | 
| | | | 
| | | | 
| | | | 
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Table 4-4: Flag Word Values (Cont. ) 


File type contained at least 
one ? character. 

(FLAGS .AND. 64).EQ.0 File type did not contain any 
2? characters. 


necessarily a device name, was 
found in the string. 


| | | 

| | | 

| | | 

| | | 

| | | 

| | | 

| | | 

| 7 | (FLAGS .AND. 128) .NE.0 | A project-programmer number 

| | | (PPN) was found. 

| | | 

| | (FLAGS .AND. 128).EQ.0 | No PPN was found (and bits 8 
| | | and 9 of this word are also 

| | ) Oye 

| | | | 

i 3 | (FLAGS .AND. 256).NE.0 | Project number was an * 

| | | character; that is, the PPN 

| | | was of the form [*,PROG]. 

| | | 

| | (FLAGS .AND. 256).EQ.0 | Project number was not an * 

| | | character. 

| | | 

| 9 | (FLAGS .AND. 512).NE.0 | Programmer number was an * 

| | | character; that is, the PPN 

| | | was of the form [PROJ,*]. 

| | | 

| | (FLAGS .AND. 512).EQ.0 | Programmer number was not an * 
| | | character. 

| | | 

| 10 | (FLAGS .AND. 1024).NE.0 | A protection code was found. 
| | | 

| | (FLAGS .AND. 1024).EQ.0 | No protection code was found. 
| | | 

|} ll | (FLAGS .AND. 2048) .NE.0 | The protection code currently 
| | | set as default by the current 
| | | job was used. 

| | | 

| | (FLAGS .AND. 2048).EQ.0 | The assignable protection code 
| | | was not used. 

| | | 

|} 12 | (FLAGS .AND. 4096).NE.0 | A colon (:), but not 

| | | 

| | | 


DCL Functions in Command Procedures 


FSPARSE 
Table 4-4: Flag Word Values (Cont. ) 
+------- tener ee ee ee ee ee ee ee ee ee eee terre ree ee ee eee ee ee ee ee ee eee eee + 
| Bit | Test | Meaning | 
+------- tee ee ee ee ee ee ee ee ee ee ee eee teen eee ee ee ee ee ee ee ee ee ee ee ee eee “ 


(FLAGS .AND. 4096).EQ.0 No colon was found (no device 
was specified); bits 13, 14, 


and 15 of this word are also 


0. 
13 (FLAGS .AND. 8192).NE.0 A device name was found. 
(FLAGS .AND. 8192).EQ.0 No device name was found; bits 
14 and 15 of this word are 
also 0. 
14 (FLAGS .AND. 16384) .NE.0 Device name specified was a 
logical device name. 
(FLAGS .AND. 16384).EQ.0 Device name specified was an 
actual device name; bit 15 of 
this word is also 0. 
15 (FLAGS .AND. 32768).NE.0 The logical device name 


of the following reasons: 


o The device name contained 
an underscore but did not 
correspond to any 
physical device on the 
system. 


o The device name did not 
contain an underscore but 
could not be translated 
to a physical device 
name. 


The device name specified, if 
any, was either an actual 
device name or a logical 
device name to which a 
physical device has been 
assigned. 


(FLAGS .AND. 32768) .EQ.0 


| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| specified was invalid for one | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
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Table 4-4: Flag Word Values (Cont.) 

5 pos Pee he ee OR ae Hee Gees + 
| Bit | Test | 
eae Shae $2 So patie eRe eee eee eee es + 
| | | 
Oe Sa. |] | 
| | | 
| | | 
| | | 
| | | 
fate ees Pere ee er eee ee eee eee + 


Reserved; returned as 0, 
except when the file-spec is 
invalid, in which case all 
bits (0-31) are set and the 
value returned is -l. 


The following example uses the FSPARSE function to determine if a 


device is a disk: 


!'Define default list file 
DEFAULT = "_SY:.LST" 


{Prompt for output file-spec 
INQUIRE OUTFIL "Output to" 


!'Build complete file-spec 
OUTFIL 


'Save device status 
DEV_STS 


'Ensure device is a disk 
IF (DEV_STS .AND. 255) 


Nn In NWN in IN tf) Nn tf In 


2NE. 


S NOTDSK: 


This example: 


FSPARSE(OUTFIL, DEFAULT) 


FSPARSE(OUTFIL,,"STATUS") 


QO THEN GOTO NOTDSK 


Assigns the default-spec value "_SY:.LST" to the symbol 


Uses the INQUIRE command to prompt for the file-spec to be 


O 
DEFAULT. 
O 
parsed and assign the result to the symbol OUTFIL. 
O 


specification after parsing both OUTFIL and DEFAULT. 
assigns the new file-spec to the symbol OUTFIL, 


the previous assignment. 


Uses the FSPARSE function to return a complete RSTS/E file 


DCL 
overriding 
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Uses the FSPARSE function to assign the device status (as a 
32-bit integer) to the symbol DEV_STS. 


Uses the IF command to test the device status to determine if 
the device is a disk. 
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FSPRIVILEGE 


The FSPRIVILEGE function returns one of two values: 


o The integer value 1 (true) if your job’s current privileges 
match those specified in the list of privilege keywords 


Oo The integer value 0 (false) if the job’s privileges do not 
match 


The format of the FSPRIVILEGE function is: 
FSPRIVILEGE("[NO]privilege[,...]") 
where: 


[NO]privilege is a privilege keyword optionally preceded by "NO". 
If you specify several privilege keywords, you must 
separate them with commas (,) and you must enclose the 
entire list within quotation marks ("). When you 
specify [NO]privilege, the function returns the value 
1 (true) only if the current job does not have the 
Specified privilege. 


Table 4-5 lists the valid privilege keywords and describes the 
function of each. 


Table 4-5: Summary of Privileges 


tre r ree ee eee pre ee ee ee ee ee ee ee ee eee + 
| Privilege | Description | 
tee eee eee per rr ee eee ee ee ee ee eee eee eee + 
| | | 
| DATES | Change system clock and file dates. | 
tee r eee ee eee frre ee ee ee ee ee ee ee ee ee ee ee eee + 
| | | 
| DEVICE | Access restricted devices. | 
t---- +e ee eee porn ee ee ee ee ee ee ee ee ee ee ee eee eee eee eee 4 
| | | 
| EXQTA | Exceed disk quota or memory maximum. (Not usually | 
| | given to users; used by privileged programs. ) | 
+---- +e eee per ee ee ee ee ee ee ee ee ee ee ee ee ee eee + 
| | | 
| GACNT | Perform accounting operations on accounts in the | 
| | user’s group. | 
t---- ee ee ee tere ee ee ee ee ee ee ee ee ee ee ee eee ee eee eee ee “ 
| | | 
| GREAD | Read or execute any file in the user’s group, | 
| | regardless of protection code. | 
i tr rr ee ee ee ee ee ee ee ee ee ee eee eee + 
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Table 4-5: Summary of Privileges (Cont. ) 
too eee ee eee 5 a ee + 
| Privilege | Description | 
torre eee per ee ee ee ee ee ee ee eee + 
| | | 
| GWRITE | Write or create/rename any file in the user’s group, | 
| | regardless of protection code. | 
Sr pe ee ee ee ee ee ee eee + 
| | | 
| HWCFG | Set hardware configuration parameters; for example, | 
| | set terminal characteristics. | 
5 Her ee ee ee ee ee ee ee ee eee + 
| | | 
| HWCTL | Control devices; for example, disable a device or hang | 
| | up a dial-up line. | 
5 pr ee ee ee ee ee ee ee eee + 
| | | 
| INSTAL | Install run-time systems, swap files, and resident | 
| | libraries. | 
+--+ ---- eee pe ee ee ee ee ee ee eee ee eee ~ 
| | | 
| JOBCTL | Manipulate other jobs; for example, detach or kill a | 
| | Job. | 
tree rere eee 5 + 
| | | 
| MOUNT | Mount or dismount disks other than /NOSHARE. | 
to-- ee ee ee ee He ee ee ee ee ee ee ee ee eee + 
| | | 
| PBSCTL | Control print/batch services; for example, turn | 
| | servers on or off, change printer forms. | 
5 Se a +: 
| | | 
| RDMEM | PEEK at memory. (Not usually given to users; used by | 
| | privileged programs. ) | 
Se pr ee ee ee ee ee ee ee ee eee + 
| | | 
| RDNFS | Read disks non-file-structured. | 
+-----+------ Hen ee ee ee ee ee ee eee ee eee + 
| | | 
| SEND | Broadcast to terminals and send messages to restricted | 
| | receivers. | 
t---- eee eee per ee ee ee ee ee ee eee ee ee ee “ 
| | | 
| SETPAS | Change your own password. | 
t--- ee eee ee Herr ee ee ee ee ee ee ee ee eee + 
| | | 
| SHUTUP | Shut down the system. | 
t--- ee eee per re ee ee ee eee eee ee eee + 
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Table 4-5: 


Summary of Privileges (Cont. ) 


Set software configuration parameters; for example, 
installation name. 


Control software components; for example, turn 
DECnet/E on and off. 


Perform restricted I/O operations; for example, gain 
write access to files in account [0,*], or set the 
privilege bit on executable files. 


Perform functions that could easily modify the system; 
for example, poke memory. 


Control system tuning parameters; for example, caching 
or job priority. 


RSTS/E. 


code. 


Write any file regardless of protection code. 
Create/rename any file except in account [0,*]. 
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The following example uses the FSPRIVILEGE function to determine if a 
user has HWCTL privilege: 


HWCTL PRIV = FSPRIVILEGE("“HWCTL" ) 
IF HWCTL PRIV THEN GOTO CONTINUE 
WRITE 0 "?Privilege HWCTL required" 
EXIT 

CONTINUE: 


MUNN MN YM 


In this command procedure, if the user has HWCTL privilege, the 

procedure continues to execute. If the user does not have HWCTL 
privilege, DCL displays a message on the user’s terminal and the 
procedure exits. 
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FSRIGHT 

The FSRIGHT function extracts a substring from a string starting at 
the position you specify and ending at the right-most position of the 
String. This function is similar to the BASIC-PLUS RIGHT function. 
The format of the FSRIGHT function is: 


FSRIGHT(string,position) 


where: 
string is the string from which to extract the substring. 
position is an integer that specifies the starting position of 


the substring. If the position argument is negative 
or 0, the function returns the entire string. If the 
position argument is greater than the length of the 
string, the function returns a null string. 


The following example uses the FSRIGHT function: 


S CHARS = FSRIGHT( "ABCDEFGHI",6) 
S SHOW SYMBOL CHARS 
CHARS = "FGHI" 


In this example, the FSRIGHT function returns the string starting at 
position 6. DCL then assigns the resultant substring, "FGHI", to the 
symbol CHARS. 
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FS SEARCH 


The FSSEARCH function searches a disk directory for the file you 
specify and returns its full RSTS/E file specification as a string. 


Note 


You cannot use the FSSEARCH function at the 
interactive level. 


The format of the FSSEARCH function is: 
FSSEARCH([file-spec] ) 
where: 


file-spec is a string expression that specifies the file to 
locate. You must specify a file-spec the first time 
you use the FSSEARCH function. A complete RSTS/E 
file-spec consists of the fields: 


_dev:[proj,prog]filnam.typ 


You can use wildcard characters in the proj, prog, 
filnam, or .typ fields. If you specify an invalid 
file-spec or a device other than a disk, DCL displays 
an error message. 


DCL returns a null string when you do not include the 
file-spec argument in the initial use of the FSSEARCH 
function, or when the FSSEARCH function cannot find 
the specified file(s). 


Use FSSEARCH to return information about one file, or about a series 
of files in your directory. You can also display information about 
files in other directories, if you have read access to those files. 


The first example shows how to use the FSSEARCH function to obtain 
information about one file: 


S REPORT FILE = FSSEARCH("REPORT.DAT" ) 


After this command executes, the symbol REPORT_FILE is assigned the 
string value: 


_SY:[4,214]REPORT. DAT 
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The second example uses the FSSEARCH function with a loop to obtain 
information about all files in your account that have the same file 


type: 


NEXT FILE = FSSEARCH(" SY:*.B2S") 
LOOP: 
IF NEXT FILE .EQS. "" THEN EXIT 


WRITE 0 NEXT FILE 
NEXT FILE = FSSEARCH( ) 
GOTO LOOP 


Lr I Ud Ut Un 


This example uses a wildcard and a loop to locate all occurrences of 
files with the file type .B2S. DCL returns a null string, after 
displaying all .B2S files in your directory. 


If you have read access to other directories, you can also obtain 


information about files in those directories. For example: 
S$ SYSTEM_WIDE = FSSEARCH(" SY:[*,*]*.LST") 
S$ LOOP: 
S IF SYSTEM WIDE .EQS. "" THEN EXIT 
S WRITE 0 SYSTEM_WIDE 
S SYSTEM _WIDE = FSSEARCH( ) 
$ GOTO LOOP 


This command procedure displays all .LST files (in all directories on 
the system) to which you have read access. 
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FSSTRING 

The FSSTRING function converts an integer expression to a string. 
The format of the FSSTRING function is: 

FSSTRING(expression) 


where expression is an integer expression or symbol that equates to an 
integer expression. 


The following example uses the FSSTRING function: 


S A= 5 

S$ B = FSSTRING(-2 + A) 
S$ SHOW SYMBOL B 

B —_ aa to 


In this example, the FSSTRING function converts the result of the 
expression (-2 + A) to the numeric string "3". Note that the symbol A 
has the integer value 5. 
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FSTERMINAL 


The FSTERMINAL function returns the keyboard (KB) number for the 
current job, as an integer. 


The format of the FSTERMINAL function is: 
FSTERMINAL( ) 


Use the FSTERMINAL function in command procedures that need to 
determine a job’s keyboard number or determine if a job is currently 
detached. If the job is detached, this function returns a negative 
value, which is the two’s complement of the terminal from which the 
job detached. 


The following example shows the use of the FSTERMINAL function: 
'Broadcast message to my terminal 


$ 
S TERM = FSTERMINAL 
S BROADCAST KB’TERM’ "Assembly finished" 
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FSTIME 
STIME 
The FSTIME function returns the current date and time. 
The format of the FSTIME function is: 
FSTIME() 
This function returns a string of the form: 
date time 
where: 
date is the current date, ina format defined by your 
system manager. The date can have the format 
dd-mmm-yy or yy.mm.dd. 
time is the current time, ina format defined by your 
system manager. Time can be either 24-hour or AM/PM 


format. 


The FSTIME function always returns a string. The length of the string 
depends on the format of the system date; no trailing blanks are 
returned. However, the time field is always returned starting at 
position 11 in the string, regardless of the format of the system date 
returned, because one or more spaces are inserted between the date and 
time fields to force the time string to begin at position ll. 


The following example shows the use of the FSTIME function: 


S WRITE 0 "Program started on ", FSTIME 
Program started on 12-Jun-85 07:36 AM 
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FSTYPE 


The FSTYPE function returns a string indicating the type of a symbol 
Or expression. 


The format of the FSTYPE function is: 


FSTYPE(symbol ) 
FSTYPE( expression) 


The FSTYPE function returns one of the following keyword strings: 
Keyword Meaning 


INTEGER The symbol has an integer value, or the expression 
result is an integer. 


STRING The symbol has a string value, or the expression 
result is a string. 


null string The symbol is not defined, or the expression contains 
one or more undefined symbols. 


The following example uses the FSTYPE function: 


S !Initialize COUNT if not yet defined 
S IF FSTYPE(COUNT) .EQS. "UNDEFINED" THEN COUNT == 0 


In this example, the FSTYPE function determines the symbol’s type. If 
COUNT is an undefined symbol, then the procedure starts counting at 0. 
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FSUSER 


The FSUSER function returns the project-programmer number (PPN) for 
the current job. 


The format of the FSUSER function is: 
FSUSER( ) 


The FSUSER function returns a string of the form: 


[proj,prog] 


where: 
proj is the project number for the current job. 
prog is the programmer number for the current job. 


Use this function in command procedures that need to use their own 
job’s PPN as input to a task or compare and extract information from a 
list, such as a DIRECTORY or SYSTAT listing. For example: 


S ID = FSUSER() 
S WRITE 0 "You are account ’’ID’,." 
You are account [1,214] 


In this example, DCL assigns the PPN returned by FSUSER to the symbol 
ID. The WRITE command then displays the PPN at the user’s terminal 
because you specified channel 0. 
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FSVERIFY 


The FSVERIFY function returns the current verification status as an 
integer, indicating 1 if verification is on, and 2 if verification is 
off. If you specify an argument, this function also turns 
verification on or off. 


The format of the FSVERIFY function is: 
FSVERIFY([value] ) 
where: 


value is an optional argument that you can specify to turn 
verification on or off. DCL examines the low-order 
bit in the argument and turns verification off if the 
value is 0, or on if the value is l. 


Use the FSVERIFY function to enable or disable verification for a 
group of commands and then restore verification to its previous state. 
For example: 


'Save verify state and set NOVERIFY 
SAVE VERIFY = FSVERIFY() 
SET NOVERIFY 


Yi tf IN 


S !Restore verify state 
S IF SAVE VERIFY THEN SET VERIFY 


In this example, the assignment statement saves the current 
verification status in the symbol SAVE VERIFY. Then the SET NOVERIFY 
command disables verification. The IF command tests the value of 
SAVE VERIFY. If it is 1, showing that verification was previously on, 
the SET VERIFY command executes and verification is restored. If 
SAVE VERIFY has a value other than 1, verification was initially off. 
In this case, the SET VERIFY command is not executed, so verification 
remains off. 
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When you use an argument, 


FSVERIFY still returns the current 
verification status. 


However, the command interpreter then examines 
the low-order bit in the argument and turns verification off if the 
value is 0, or on if the value is 1. For example: 


S !Save verify state and set NOVERIFY 
S SAVE VERIFY = FSVERIFY(0) 


S$ !Restore verify state 
S$ SAVE_VERIFY = FSVERIFY(SAVE_VERIFY) 


In this example, the FSVERIFY function turns verification off, 


and 
then restores the previous setting at the end of the procedure. 


Chapter 5 


Interacting with Command Files 


This chapter describes how to control input to and output from command 
procedures. It tells you how to: 


o Pass data to a command procedure 
o Return data from a command procedure 
o Display data from a command procedure 


o Supply data to a program in a command procedure 


Passing Data 


When you write a command procedure, you need to be able to pass input 
data to the procedure when it executes. DCL provides the following 
ways to do this: 


Oo You can pass data to a command procedure uSing parameters 


Oo You can issue a prompt to the user at the terminal, and the 
user can enter data interactively 


The following sections describe these methods in greater detail. 


Interacting with Command Files 


Note 


You can also read data from a file within a command 
procedure. For example, you could design a command 
procedure that displays informational records at a 

terminal, or that reads the records of an assembly 

listing file to search for possible errors. 


See Chapter 6 for descriptions of the OPEN, READ, and 
CLOSE commands, which you use to read data from a file 
within a command procedure. 


Passing Parameters 


When you invoke a command procedure using the at (@) command, you can 
pass it up to eight parameters by placing the values of the parameters 
after the file specification of the command procedure. Separate the 
parameters with one or more spaces or tabs. You can specify a 
parameter value as one of the following: 


O 


Literal -- Specify the literal with or without quotation 
marks ("), depending on whether you want to preserve spaces, 
tabs, and lowercase characters. The following example passes 
the values "JOHN" and "DOE" to DATA.COM: 


S$ @DATA John Doe 


Use quotation marks to preserve spaces, tabs, or lowercase 
characters. The following example passes the single value 
"John Doe" to DATA.COM: 


S$ @DATA "John Doe" 


Symbol -- To pass the value of a symbol, place an apostrophe 
(’) before and after the symbol. The following example 
passes the values "JOHN" and "DOE" to DATA.COM: 


S NAME = "John Doe" 
S$ @DATA ‘NAME’ 


When DCL passes a symbol, it removes quotation marks that 
enclose a literal. To preserve spaces, tabs, and lowercase 
characters in a symbol value, specify the enclosing quotation 
marks as part of the symbol value. To include quotation 
marks as part of a literal value, double the quotation marks 
inside the literal string. The following example passes the 
Single value "John "Mr. Average" Doe" to DATA.COM: 


S$ @DATA "John ""Mr. Average"" Doe" 


3-2 


Interacting with Command Files 


DCL treats all types of parameters as literal string values and 
assigns them to the local symbols’ Pl through P8: Pl is assigned the 
first parameter value; P2 the second; P3 the third; and so on. If you 
pass more than eight values, DCL returns an error message and does not 
execute the procedure. If you pass fewer than eight values, DCL 
assigns null values to the remaining symbols. In addition, you can 
pass a null parameter explicitly, by using double quotation marks in 
the list of parameters. 


In the next example, you pass parameters to the procedure DATA.COM: 


S @DATA "John Doe" "" 24 "(603) 555-8003" 
When DCL processes this command string, it assigns the following 
values to Pl through P8: 


Pl = "John Doe" 

P2 _— 06 00 

P3 = "24" 

P4 = "(603) 555-8003" 
P5 _ 00 00 

P6 = oo 09 

P7 _ to 00 

P8 _ OF 08 


When DCL enters a nested procedure, it assigns the local symbols Pl 
through P8 the new parameters passed by the invoking procedure. Note 
that the local symbols Pl through P8 in the nested procedure are not 
related to the local symbols Pl through P8 in the invoking procedure. 
For example, suppose DATA.COM invokes NEWDATA.COM with the command: 


S @NEWDATA ‘Pl’ 
In NEWDATA.COM, Pl through P8 are defined as follows: 


Pl "JOHN" 
P2 = "DOE" 
P3 _ oo 00 

P4 -_ 00 08 

P5 - v8 00 

P6 _ 10 08 

P7 _ oo 09 

P8 - ot 00 
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Prompting for Symbol Values 


When you want a user to enter data interactively at a terminal, you 
can use the INQUIRE command to define a value for a symbol while the 
procedure is executing. INQUIRE prompts for a value at a user’s 
terminal and waits for a response. After the user enters a response, 
INQUIRE reads the value from the terminal and assigns it to the 
specified symbol name. 


Format 
INQUIRE symbol-name [prompt-string] 


Command Qualifiers Defaults 


/[NO]PUNCTUATION / PUNCTUATION 
/{NO]ECHO /ECHO 
/EXIT[=label ] See discussion 
/TIME_OUT=seconds See discussion 
/GLOBAL 
/ LOCAL 
pr ee ee ee + 


Command Parameters 
symbol-name 


Is a name from 1 to 255 characters long. DCL assigns a string 
value to the symbol name. 


prompt-string 


Is the prompt to display at the terminal when the INQUIRE command 
executes. If you do not specify a prompt string enclosed in 
quotation marks, the command uses the symbol name to prompt for a 
value. 


Command Qualifiers 

/([NO] PUNCTUATION 
Indicates whether to append a colon and a space to the prompt 
string when INQUIRE displays it. The default is /PUNCTUATION. 


To suppress the colon and space, use the /NOPUNCTUATION 
qualifier. 
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/{NO]ECHO 


Indicates whether to display the user’s response to the prompt at 
the terminal. The default is /ECHO. To suppress the display of 
sensitive information at the terminal, such as passwords, use the 
/NOECHO qualifier. 


/EXIT[=label ] 


Specifies the label of the line in the command procedure to be 
given control when a CTRL/Z is encountered. If you do not 
specify /EXIT, or if you specify /EXIT without a label, the 
command procedure exits on a CTRL/Z. 


/TIME OUT=seconds 
Specifies the number of seconds to wait for input. If no input 
is received within the specified time, DCL assigns a null string 
to the symbol name. The number of seconds must be in the range l 
to 327674 

/GLOBAL 
Places the symbol in the global symbol table. /GLOBAL is the 
default at the interactive command level. 

/LOCAL 
Places the symbol in the local symbol table for the current 
command procedure. /LOCAL is the default for all command levels 


except the interactive level. DCL displays an error message when 
you specify /LOCAL at the interactive command level. 


Examples showing how to use the INQUIRE command follow. 
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Use the /NOPUNCTUATION qualifier to suppress the colon and space that 
are normally added after the prompt. For example: 


S$ INQUIRE/NOPUNCTUATION IN "Input from? " 
S$ INQUIRE/NOPUNCTUATION OUT "Output to? " 


When these commands execute, the following prompts appear at the 
terminal: 


Input from? 
Output to? 


To define a global symbol name with the INQUIRE command, use the 
/GLOBAL qualifier. For example: 


S$ INQUIRE/GLOBAL FILE "Filename" 


When this command executes, DCL enters the symbol name FILE and the 
response in the global symbol table. 


To define a local symbol name with the INQUIRE command, use the /LOCAL 
qualifier. For example: 


S INQUIRE/LOCAL FILE "Filename" 


When this command executes, the following prompt appears at the 
terminal: 


Filename: 


After you enter a response, DCL places the symbol name FILE and the 
value you enter in the local symbol table for the current command 
procedure. 


If you press the RETURN key in response to an INQUIRE command, DCL 
assigns a null value to the specified symbol name. For example: 


S INQUIRE FILE "File" 
> IF FILE .EQS. "" THEN EXIT 


In this example, the INQUIRE command is followed by a test to 
Getermine whether a null value was entered. If a null value was 
entered, the procedure exits. 
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Returning Data 
To return a value from a command procedure (either to a calling 
procedure or to the interactive level), you must assign the value to a 


global symbol. The global symbol can be read at any command level. 
Use comments to explain the use of any global symbols. 


To create a global symbol, specify the value to be passed on the right 
side of a global assignment statement. For example: 


S$ @DATA "John Doe" 


DATA. COM 


S ! Pl is a full name 
S ! NAME.COM returns the last name in the 
S ! global symbol LAST_NAME 
3 
S @NAME ‘Pl’ 
NAME.COM 
S ! Pl is a first name 
S ! PpP2 is a last name 
$ ! return P2 in the global symbol LAST_NAME 
$ LAST NAME == P2 
S EXIT 
S$ ! write LAST _NAME to the terminal 
S$ WRITE 0 "LAST NAME = ""’'LAST NAME’""" 
LAST NAME = "DOE" 


In this example, DATA.COM passes a full name to NAME.COM. NAME.COM 
places the last name in the global symbol LAST_NAME. DATA.COM reads 
the value by referencing the global symbol. 
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Displaying Data 


You can display data in a command procedure by using the WRITE 
command. 


Use the WRITE command to display literal or symbol values, or a 
combination of both, at a terminal: 


o Literal -- Enclose the text in quotation marks ("). The 
following example displays the text "Two files were 
Written. % 


S WRITE 0 "Two files were written." 


o Symbol Value -- The following example displays the text 
"STATUS.DAT": 7 


S FILE = "STATUS.DAT" 
S WRITE 0 FILE 


o Combination of literals and symbol values -- Enclose the text 
in quotation marks. Where a symbol appears, precede it with 
two apostrophes and follow it with one apostrophe. The 
Following example displays the text "STAT1.DAT and STAT2.DAT 
were written.": —_ 


S AFILE "STAT!.DAT" 
S BFILE = "STAT2.DAT" 
S WRITE 0 "’’AFILE’ and ’’BFILE’ were written." 


See Chapter 6 for a complete description of the WRITE command. 


Supplying Data to a Program 


The following sections describe how to supply data to a program either 
from inside a command procedure or interactively at a terminal while 
the procedure executes. 


Reading Data in a Program 


When a program requiring terminal input runs directly under control of 
a keyboard monitor, the program receives its input directly from the 
user’s keyboard. However, when the same program runs under control of 
a command procedure, all input normaily received from the terminal is 
read from the current command file. 


For example, 
numbers and prints the average value. In interactive mode, the 
program dialogue is: 
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the following program prompts a user for a list of 


S$ RUN AVRAGE 


How 
lst 
2nd 
3rd 


many numbers? 4 


number? 
number? 
number? 
number? 
average 


You can also run the AVRAGE program from a command procedure uSing a 
predefined set of numbers. The procedure would look like this: 


S RUN AVRAGE 


When the AVRAGE program requests data from the terminal, the monitor 
intercepts the request and reads the data lines from the command file 


instead. 


When you design this type of noninteractive command 


procedure, you must eliminate any unexpected prompting that could 
cause the procedure to read the wrong data. 


You can also use the SET NODATA command (see the next section) to run 
a program from a command procedure that supplies the program with 
input from the terminal. 
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Supplying Data to a Program from a Terminal 


By default, the SET DATA command is in effect when you invoke a 
command procedure. Thus, any data that a program or a keyboard 
monitor (other than DCL) requests must be supplied in the command 
file. However, you can redirect data input back to a terminal by 
issuing the SET NODATA command. The SET NODATA command tells DCL to 
read all data required by a program or a command from the terminal 
rather than from the command file. 


Format 
SET [NO]DATA 


Command Qualifiers Defaults 


/END_OF_DATA="char" /END_OF_DATA="S$" 


Command Qualifiers 
/END_OF_DATA="char" 


Identifies an alternate prefix character to signal the end of 
data. Whenever a line is read from the command file that begins 
with the alternate prefix character, control returns to the DCL 
keyboard monitor and any command following the alternate prefix 
executes. 


The alternate prefix character stays in effect until the data 
list terminates. After control returns to DCL, the standard §$ 
character is reenabled. 


Note that you should never begin a data line with a $ character in the 
First space, even if you define an alternate prefix character with the 
SET DATA/END_OF_ DATA command. In cases where a program requires its 
data to begin with a $ character, insert a leading space or a tab 
Space before the $ character to distinguish it from a DCL command 
line. (Most programs routinely remove leading spaces and tabs from 
its data lines.) 


For example, the following command file runs PIP to copy a file from 
your account to the system library ($) account: 


S SET DATA 

S RUN SPIP _ 
<TAB>SFOO=BAR 
S EOD 
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Since PIP’s data line begins with a tab space, RSTS/E correctly treats 
it as a data line. The tab space does not affect the PIP command, 
Since PIP strips leading spaces and tab spaces. Note that if you did 
not include the tab space in this example, RSTS/E would handle the 
data line as a DCL command line -- in this case, by stopping PIP and 
executing the line as a DCL aSsignment statement. 


Use the SET DATA command to supply data to a program from inside a 
command procedure, specifying an alternate prefix character that 
Signals the end of data. For example: 


S$ SET DATA/END_ OF _DATA="<" 
S CREATE LOGIN.COM 

SRUN SSYSTAT 

SSYSTAT.DAT 


(data lines) 


< 
S EXIT 


In this example, SRUN SSYSTAT and SSYSTAT.DAT are data lines for the 
CREATE command. When the alternate prefix character (<) is read, 
control returns to the DCL keyboard monitor. Note that if the prefix 
character were a $, the procedure would interpret the first $ in SRUN 
SSYSTAT as the end of data signal. 


Use the SET NODATA command to supply a program with input from the 
terminal. The SET NODATA command stays in effect until you issue a 
SET DATA command or until the current command procedure exits. 


In nested command procedures, each level maintains its own [NO]DATA 
setting and alternate prefix character. When a command procedure 
exits, DCL restores the [NO]JDATA setting and alternate prefix 
character of the higher-level procedure. 


The following example shows the command procedure AVRAGE.COM that runs 
the program AVRAGE.TSK, letting you supply data at your terminal: 


AVRAGE. COM 
SET NODATA 


RUN AVRAGE 
EXIT 


in IN 
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Note that this procedure does not include data lines for the AVRAGE 
program. The SET NODATA command tells DCL to read data from the 
terminal rather than from the command file. For example, the dialogue 
at your terminal would appear as: 


S @AVRAGE 


How many numbers? 4 
lst number? 91 
2nd number? 8/7 
3rd number? 92 
4th number? 90 
The average is 90.0 


S 


By using the SET NODATA command, you can supply different sets of data 
to a program without modifying the command file. 


Signaling the End of a Data List 


Use the end-of-data (SEOD) command to signal the end of a data list 
and exit from a program within a command procedure. 


The only function of the SEOD command is to terminate data lists toa 
program or to another DCL command. Although you can use any DCL 
command preceded by the $ character to exit from a program, the SEOD 
command provides a standard way to end a data list, and return to the 
DCL keyboard monitor. 


Exiting from a Program in a Command File 


The RSTS/E monitor takes the following steps to exit from a program 
and return to the DCL keyboard monitor. Whenever the monitor 

encounters a $ prefix character, a special prefix character, an SEOD 
command, or when it reaches the end of the current command file, it: 


Oo Forces up to five CTRL/Z characters to the program, as 
needed. This step causes most RSTS/E programs to exit 
normally. 
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Oo Forces up to two CTRL/C exits to the program, as needed. 
This step aborts any program that does not perform its own 
CTRL/C handling. 


Oo Forces a double CTRL/C exit to the program. This step aborts 
any program that uses CTRL/C as a normal way to exit. 


o Aborts the program immediately, and returns control to the 
DCL keyboard monitor. This step is unconditional, and 
specifically guards against CTRL/C trapping. 


Detaching Programs in a Command Procedure 


When designing command files to run programs that detach, you 
generally want the command procedure to continue executing after a 
program detaches. For example, the START.COM start-up command file 
must continue processing after the OPSER program detaches. 


RSTS/E allows a command procedure to continue executing when it runs 
programs that detach. If a program running within a command procedure 
detaches, RSTS/E detaches the current job, creates a new job at your 
terminal, and then transfers all of the DCL context from the detached 
job to the new job so that the command procedure can continue 
executing. 


Therefore, you should consider the following points when writing 
command files that include programs that detach: 


o RSTS/E does not create a new job if the detach request leaves 
the terminal either allocated to the job or open on any 
non-zero channels. In this case, the job detaches, and the 
command procedure detaches with it. You can set the "close" 
flag in the detach system call to deallocate the terminal and 
close any non-zero channels on which the terminal is open. 


o RSTS/E does not detach a job if no job slots are available to 
create the new job. 


o When a program detaches, the command procedure continues to 
execute, but in the newly created job; therefore, the FSJOB 
function will return a different job number than the number 
it returned before the program detached. See Chapter 4 for a 
complete description of the FSJOB function. 


o If you later attach to a job that detached within a command 
procedure, it will not contain any DCL symbols, since all DCL 
syntax was moved to the newly created job. 
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Passing Symbol Values to a Program 


Only applications that run under DCL can perform symbol substitution. 
Therefore, you must take a different approach when you need to pass a 
symbol value to a program running under control of another run-time 
system. For example, the following incorrect command procedure runs 
the PIP program under the RT11 run-time system: 


MOVE .COM 


S RUN SPIP 
LB:*,* = "Pl! 
S EOD 


Suppose you execute this procedure with the command: 
S$ @MOVE TEST.FIL 


You might expect the value TEST.FIL to be substituted for the symbol 
Pl during execution. However, this does not occur because the RT1ll 
run-time system does not perform symbol substitution. Only DCL 
command lines can include symbol substitution. 


To pass the value TEST.FIL to PIP, you must create a temporary command 
file and execute it as a nested procedure within MOVE.COM. For 
example: 


MOVE.COM 


S OPEN/WRITE/REPLACE 1 MOVE1.COM 
S WRITE 1 "SRUN SPIP" 

S WRITE 1 "LB:*.* = ''pl]'" 

S WRITE 1 "SEOD" 

S WRITE 1 "SEXIT" 

S CLOSE 1 

S @MOVEL 

S DELETE MOVE1.COM 


You create a temporary command file using a series of OPEN and WRITE 
commands that are executed under DCL, which performs the symbol 
substitution. Now execute MOVE.COM with the command: 


S @MOVE TEST.FIL 


During execution, DCL substitutes the value TEST.FIL for the symbol 
Pl, and PIP copies TEST.FIL from SY: to LB:. 


Chapter 6 


File Input and Output 


This chapter describes how to combine DCL commands with the 
programming and symbolic capabilities of command procedures to 
manipulate disk files on RSTS/E systems. This chapter includes 
techniques for using: 


o The OPEN command to create new files or access existing files 
o The READ command to read from files 

o The WRITE command to write to files 

o The CLOSE command to explicitly close files that you open 


The basic steps in reading and writing to files from a command 
procedure are: 


1. Open the file -- Use the OPEN command to open the file for 
reading or writing. You must also assign a channel number in 
the range 1 to 13 so that you can later refer to the file. 


2. Read or write to the file -- Use the READ or WRITE command to 
read from or write to the file, specifying the channel number 
on which the file is open. 


3. Close the file -- Use the CLOSE command to close the file, 
specifying the channel number on which the file is open. 


Note that a file stays open until you close it or until you 
log out of the system. 


You can open, read, write, or close disk files that have the following 
file organizations and record formats: 
o RSTS/E stream ASCII (native mode) 


Oo RMS sequential 
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Oo RMS stream 

o RMS variable 

o RMS fixed 

Oo RMS carriage control IMPLIED/NONE 


o RMS span/nospan 


Opening Files 


The OPEN command opens a file either for reading or writing. 


Format 
OPEN channel-number file-spec 


Command Qualifiers Defaults 


/APPEND /READ 
/([NO]REPLACE See discussion 
/WRITE /READ 

Prompts 


Channel: channel-number 


| 
| 
| 
| 
| 
| /READ /READ 
| 
| 
| 
| 
| File: file-spec 


Re 


Command Parameters 
channel-number 


Is a channel number in the range 1 to 13 on which to open the 
file. You can specify channel-number either as a literal or as a 
symbol that evaluates to a number. Subsequent READ, WRITE, and 
CLOSE commands refer to the file by using the channel-number. 

You get an error message if you specify a channel-number outside 
the range of 1 to 13, or when you specify a channel number 
already in use. 
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file-spec 


Specifies the file to open for input or output. You can use any 
valid RSTS/E file specification; however, you cannot use 
wildcards in the file specification. If you omit the file type, 
it defaults to .DAT. 


Command Qualifiers 
/APPEND 


Specifies that new records are to be appended to the end of an 
existing disk file. If the file does not exist, RSTS/E creates a 
new file. 


Note 
You can only use the /APPEND qualifier for RSTS/E 
stream ASCII (native mode) disk files. An error 


message displays if you use /APPEND for non-disk 
files or files with RMS attributes. 


/ READ 


Opens a file for reading. /READ is the default when you do not 
specify a qualifier with the OPEN command. 


/REPLACE 
/NOREPLACE 


Specifies whether to replace an existing file with a new file. 
If the file that you specify already exists: 


o /REPLACE tells RSTS/E to delete the existing file and create 
a new file. 


o /NOREPLACE tells RSTS/E not to replace the file if it exists; 
in this case, an error message displays. 


If you specify neither qualifier, then RSTS/E issues a warning 
message and asks if you want to replace the file. 
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You should always specify this qualifier from within a command 
procedure if you are not sure the file exists. You can use the 
FSSEARCH function (see Chapter 4) to check the existence of a 
file within a command procedure. 


Note that the /[NO]REPLACE qualifier requires the /WRITE 
gualifier and conflicts with the /APPEND qualifier. 


/WRITE 


Opens a file for writing. If the file already exists, then DCL 
deletes it and creates a new file (depending on the /[NO]REPLACE 
qualifier). : 


When you open a file, you specify whether it is to be read from or 
written to and assign it a channel number. Use the channel number in 
subsequent READ and WRITE commands to refer to the file. You cannot 
use READ or WRITE commands to access an open file either from within a 
program, or from keyboard monitors other than DCL. In addition, 
because channel 0 always specifies the user’s terminal, you do not 
need to use an explicit OPEN command to write to the user’s terminal. 


The following example uses the OPEN command in a command procedure: 


S$ ON ERROR THEN GOTO OPEN_ERROR 
S FILLS = -“FILEL.DAT" 

S OPEN/READ 1 ‘FILE’ 

S FILE = "FILE2.DAT" 

S OPEN/WRITE 2 'FILE’/REPLACE 

S ON ERROR THEN EXIT 

S$ CLOSE 1 

S “CLOSE: 2 

> BRIT 

S$ OPEN_ERROR: 

S WRITE 0 "Error opening file '’FILE’" 
$ STOP 


In this example, the first assignment statement assigns the string 
value "FILE1.DAT" to the symbol FILE, and the OPEN/READ command opens 
the file for reading on channel 1. The second assignment statement 
assigns the string value "FILE2.DAT" to the symbol FILE, and the 
OPEN/WRITE command opens the file for writing on channel 2. If an 
error occurs while the system attempts to open either file, the 
procedure branches to the OPEN_ERROR routine, displays an error 
message, and returns to the interactive level. Otherwise, the 
procedure continues executing until it closes the open files and exits 
to either the calling command procedure or to the interactive level. 


6-4 
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Reading Files 
The READ command reads the next record from a file that you open for 


reading with the OPEN command and assigns the contents of the record 
to the symbol name you specify. 


Format 
READ channel-number symbol-name 


Command Qualifiers Defaults 


/(|NO]DELIMITER /NODELIMITER 

/ GLOBAL See discussion 
/LOCAL | See discussion 
Prompts 


Channel: channel-number 
Symbol: symbol-name 


| 
| 
| 
| 
| 
/END_OF_FILE=label None | 
| 
| 
| 
| 
| 
| 
| 


Command Parameters 
channel-number 


A channel-number in the range 1 to 13, that identifies the file 
to be read. You can specify channel-number either as a literal 
Or as a symbol that evaluates to a number. You get an error 
message when: 


Oo You specify a channel number outside the range 1 to 13. 
o No file is open on the specified channel. 


o The file on the specified channel is not open for reading. 


symbol-name 


Is the symbol name to which DCL assigns the contents of the 
record read in the READ command, as a string value. If you use 
the same symbol name for more than one READ command, each READ 
command redefines the value of the symbol name. The /GLOBAL and 
/LOCAL qualifiers determine whether the symbol is global or 
local. 
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Command Qualifiers 
/{NO]DELIMITER 


Tells DCL whether to include the record delimiter (such as CR/LF 
Or FF) in the returned string. The default is /NODELIMITER. The 
/DELIMITER qualifier tells DCL to append the record delimiter to 
the string. 


/END_OF_FILE=label 


Specifies the label of the line in the command procedure to be 
given control when DCL detects an end-of-file (EOF) condition on 
the read. When this condition occurs, no record is returned. If 
you do not specify an /END_OF_ FILE qualifier, the action taken 
depends on the current setting of the ON command. See Chapter 8 
for a complete description of the ON command and error handling 
in command procedures. 


/ GLOBAL 


Tells DCL to search the global symbol table for the symbol you 
specified. If DCL finds the symbol, it replaces its value. If 
DCL does not find the symbol, then it enters the symbol into the 
global symbol table. DCL searches the global symbol table by 
default when you execute a READ command at the interactive level. 


/ LOCAL 


Tells DCL to search the local symbol table for the symbol you 
specified. If DCL finds the symbol, it replaces its value. If 
DCL does not find the symbol, then it enters the symbol into the 
local symbol table. DCL searches the local symbol table by 
default when you execute a READ command at command levels other 
than the interactive level. In addition, you get an error 
message if you specify /LOCAL at the interactive level. 


Follow these steps to read data from a file: 


1. Open the file -- The OPEN/READ command opens the file for 
read access and associates the file name with a channel 
number. 

2. Begin the read loop -- File I/O is usually done in a loop 


unless you are reading or writing a single record. 
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3. Read the data from the file -- Use the READ command with the 
/END_OF FILE gualifier to read the next record in the file 
and assign its contents to a symbol. The /END_OF_FILE 
qualifier causes DCL to pass control to the label you specify 
when you reach the end of the file. Generally, you specify 
the label that marks the end of the read loop. 


4. Process the data -- Because you must read a file 
sequentially, process the current record before reading the 
next. one. 


5. Branch to the beginning of the loop -- You stay in the loop 
until you reach the end of the file. 


6. End the loop and close the file -- The CLOSE command 
disassociates the file name from the channel number and 
closes the file. 


When you issue a READ command, DCL returns the next record in the file 
aS a string value and assigns it to the symbol name you specify. Note 
that the returned string does not include any trailing line delimiter 
characters. 


You can read a record up to 255 characters long. You get an error 
message if DCL encounters a record that exceeds this limit. 


DCL updates the SSTATUS and SSEVERITY symbols whenever an error (other 
than an EOF trapped by the /END_OF FILE qualifier) occurs on a read, 
and then bases control on the current ON setting. See Chapter 8 for 
more information. 


The following example uses a READ command in a command procedure: 


OPEN/READ 1 NOTICE.TXT 
LOOP: 

READ/END_OF_FILE=END 1 DATA 
WRITE O DATA 

GOTO LOOP 

END: 

CLOSE: 1 

EXIT 


MNNMNUMNMNMMN MN 


In this command procedure, you open the file NOTICE.TXT for reading on 
channel 1. The LOOP routine uses a READ command to read a record from 
the file opened on channel 1 and assign it, as a string value, to the 
symbol DATA. The WRITE command displays the symbol’s value at the 
terminal. Each time the loop is executed, a new record is read and 
assigned to the symbol DATA, and written to the terminal, until the 
entire file is read and displayed at the terminal. When the procedure 
reaches EOF, control branches to the END routine, which closes the 
file before the procedure exits. 
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Writing Files 


The WRITE command writes records to a file that you open for writing 
Or appending with an OPEN command. 


WRITE channel-number data[,...] 
Command Qualifiers Defaults 
/|[NO]DELIMITER /DELIMITER 
Prompts 


Channel: channel-number 
Data: data[,...] 


Command Parameters 
channel-number 


A channel-number in the range 0 to 13 that identifies the file to 
be written. You can specify channel-number either as a literal 
Or as a symbol that evaluates to a number. If you specify 
channel 0, the data is written to the terminal. You get an error 
message when: 


o You specify a channel number outside the range 0 to 13 
o No file is open on the specified channel 


o The file on the specified channel is not open for writing or 
appending 


data[,...] 


The data to write to the file. The data list can contain one or 
more string expressions separated by commas. If you include 
integer expressions in the data list, DCL automatically converts 
them to string expressions before writing to the file. 


DCL writes each data item to the file as a string with no 
intervening characters between each item. You must include 
Spaces if you want to separate data strings written to the file. 


File Input and Output 


Command Qualifiers 


/{NO]DELIMITER 


S 


Tells DCL whether or not to write the string with trailing 
Carriage return/line feed (CR/LF) characters. The default is 
/DELIMITER. The /NODELIMITER qualifier is useful when you need 
several WRITE commands to write a single record, or when you want 
a record delimiter other than CR/LF, such as form feed (FF). 


Note that you specify an alternate record delimiter in the data 
list. For example: 


FF = FSCHR(12) 


S WRITE/NODELIMITER 0 TEXT,FF 


In this example, you define and use form feed as an alternate record 
delimiter. 


DCL 


performs automatic symbol substitution when processing 


expressions; therefore, do not use apostrophes (’) to enclose symbol 
names that you include in the data list of a WRITE command. 


Whenever an error occurs on a write, DCL updates the SSTATUS and 
SSEVERITY symbols accordingly, and then bases control on the current 
ON setting. See Chapter 8 for more information. 


The 


following examples show how to use the WRITE command in command 


procedures: 


S 
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LOOP: 

INQUIRE/EXIT=END VAL1 "lst number" 

VAL1 = FSINTEGER(VAL1) 

INQUIRE VAL2 "2nd number" 

VAL2 = FSINTEGER(VAL2) 

WRITE 0 VAL1," + ",VAL2," = ",VAL1+VAL2 
WRITE 0 VAL1," * ",VAL2," = ",VAL1*VAL2 
GOTO LOOP 

END: 

EXIT 


In this command procedure, the INQUIRE commands prompt for symbol 
values. The WRITE commands perform automatic symbol substitution when 
processing the expressions, displaying the result at the terminal. 
When the procedure executes, the following appears at the terminal: 


lst number: 10 

2nd number: 20 

10 + 20 = 30 

10 * 20 = 200 

lst number: <CTRL/Z> 


S 
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The next example shows how to read the records from one file and how 
to write those records selectively to a new file in a command 
procedure: 


S INQUIRE IN_FILE "Specify the file to read" 
S INQUIRE OUT_FILE "Specify the file to write" 
S$ OPEN 1 'IN FILE’ 

S OPEN/WRITE 2 'OUT FILE’ 

S$ LOOP: 

S READ/END_OF FILE=DONE 1 RECORD 

S IF RECORD .EQS. "" THEN GOTO LOOP 

S WRITE 2 RECORD 

S$ GOTO LOOP 

S DONE: 

S: ‘CLOSE 2 

> CLOSE 2 

S EXIT 


This command procedure: 


o Uses INQUIRE commands to prompt for a file to read (IN_FILE) 
and the new file to write (OUT_FILE) 


o Uses OPEN commands to open both files 


o Uses a read/write loop (specifying the label to branch to 
when the last record is read) to read the records from a file 
and write those records to a new file with blank lines 
Suppressed 


o After the last record is read, branches to the DONE routine 
and exits 
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Closing Files 
The CLOSE command closes a file opened for reading, writing, or 


appending with the OPEN command and removes its channel number from 
the list of open channels. 


| Format 

CLOSE channel-number 

Command Qualifiers Defaults 
/ALL 

Prompts 


| Channel: channel-number 


Command Parameters 
channel-number 


Is a channel-number in the range 1 to 13, on which to close the 
file. You can specify channel-number either as a literal or as a 
symbol that evaluates to a number. If you specify a channel 
number on which no file is currently opened, no error message 
appears. However, DCL does return an error if you specify a 
channel-number outside the range 1 to l3. 


Command Qualifiers 
JRGL 
Tells DCL to close all open data files. 
Any file that you open with an OPEN command stays open until you 
explicitly close it using the CLOSE command, or until you log out. 
Note 
If the system manager deletes your job, or if you 
delete a batch entry, and you have files open for 


writing or appending, the most recent data written to 
the file may be lost. 
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Note that, because channel 0 always specifies the user’s terminal, any 
attempt to close channel 0 resultsS in an error. 


The 
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following example uses the CLOSE command in a command procedure: 


'Make sure that channels 1-5 are closed 
CHANNEL = 1 
LOOP: 
CLOSE CHANNEL 
IF CHANNEL .EQ. 5 THEN GOTO END 
CHANNEL = CHANNEL + 1 
GOTO LOOP 
END: 
EXIT 


In this command procedure, you assign the value 1 to the symbol 
CHANNEL. Each time the loop is executed, DCL closes a channel, 
increments the channel number, and so forth, until all five channels 
are closed. 


Chapter 7 


Controlling Execution Flow in Command Procedures 


Normal execution flow in a command procedure is sequential: DCL 
executes the commands in the procedure in order, until reaching the 
end-of-file (EOF). However, in some cases you may want to repeat a 
series of commands, skip a series of commands, or abort the command 
procedure. 


The basic commands for controlling execution flow in a command 
procedure are: 


o The IF command -- Tests the value of a symbol or expression 
and executes a given command string based on the result of 
the test 

o The GOTO command -- Transfers control to a label in the 
procedure 

o The at (@) command -- Invokes another command procedure and 


begins execution at another command level 


o The EXIT and STOP commands -- Terminate the current procedure 
and restore control to either the calling command procedure 
or the interactive command level 


The IF Command 


The IF command tests the value of an expression and executes the DCL 
command after the THEN keyword if the result of the expression is 
true. An expression is true if its integer result is odd, otherwise 
it is false. DCL converts string values to integer values before 
performing the test. See Chapter 3 for a description of how DCL 
converts strings to integers. 
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| Format | 


| IF expression THEN command | 


Command Parameters 
expression 


Defines the test to be performed. The test may consist of any 
valid DCL expression. An expression is true if the result is odd 
and false if the result is even. 


See Chapter 3 for a summary of operators and details on how to 
Specify expressions. 


command 


Defines the action to take if the result of the expression is 
true. You can specify any valid DCL or CCL command after the 
THEN keyword, optionally preceded by a §$ character. 


If the result of the expression is false, control resumes at the 
next line in the command procedure. 


The following example uses the IF command: 


S COUNT = 0 
S LOOP: 
S COUNT = COUNT + 1 


S IF COUNT .LE. 10 THEN GOTO LOOP 
S EXIT 


In this example, the IF command sets up a loop in a command procedure. 
The IF command checks the value of the symbol COUNT and performs an 
EXIT command when the value of COUNT is greater than 10. 
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The target command of an IF command can be another IF command. For 
example: 


S IF A .EQ. B THEN - 
IF C .EQ. D THEN - 
IF EF «EQ. & THEN. + 
RESULT = 1 


In this example, the IF command tests each expression in turn. If the 
result of the first expression is true, the second IF command is 
executed; if that expression is true, the next IF command is executed. 
If all the IF command expressions are true, RESULT is assigned a value 
of 1; otherwise, the assignment statement is not executed. 


You can use the @ command in an IF command to invoke another command 
procedure. For example: 


S IF A .EQ. B THEN @FILE2 
If the result of the expression A .EQ. B is true, DCL executes the 


nested procedure FILE2.COM. After the nested procedure executes, 
control returns to the next line in the calling procedure. 


Command Line Labels 

Command line labels let you identify lines in a command procedure to 
which control passes when a GOTO command executes. You can precede 
any command string in a command procedure with a label. The rules for 
entering labels are: 


o A label must appear as the first item on a command line and 
must be preceded by a $ character 


o A label must end with a colon (:;:) 
Oo You can specify only one label on a command line 
Keep the following in mind when you enter labels: 


Oo Excessive use of labels can exhaust the space available for 
local symbols 


o DCL returns an error when insufficient space exists for 
storing a label definition 


o DCL does not allow symbol substitution (apostrophes) in 
labels because it performs label processing before it 
performs symbol substitution 
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When DCL finds a label at the beginning of a command line, it enters 
the label into a local label table that shares space in the local 
symbol table. If the label already exists in the table, DCL displays 
an error message and immediately ends the procedure with a STOP 
command. For example: 


S LABELI: 


S GOTO LABEL2 


S LABELI: 


S LABEL2: 


In this command procedure, DCL enters LABEL] in the local label table 
while processing the procedure. When DCL finds the GOTO command, 
LABEL2 is not yet in the local label table. DCL scans forward through 
the procedure to locate the label. While scanning forward, however, 
DCL finds a duplicate LABEL], displays an error message, and 
terminates the procedure with a STOP command. Control immediately 
returns to the interactive level. 


The GOTO Command 


The GOTO command passes control to a labeled line in a command 
procedure. 


| Format | 


| GOTO label | 
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Command Parameters 
label 


Specifies a 1 to 255 character label that appears as the first 
item on a command line. When the GOTO command executes, control 
passes to the command following the specified label. 


The label can precede or follow the GOTO command in the current 
command procedure. 


The GOTO command is useful after a THEN clause to cause a procedure to 
branch forward or backward according to variable conditions or 
parameters that you pass to the procedure. For example: 


S IF Pl .EQS. "" THEN GOTO ERROR 
- (normal processing) 
S ERROR: 


(error processing) 


In this example, DCL tests to determine if Pl is null. If it is, then 
control passes to the label ERROR, where error processing occurs. If 
Pl is not null, then control resumes at the next line after the GOTO 
command. 


You can also use the GOTO command to set up loops in a command 
procedure. For example: 


S NUM = 0 
S LOOP: 
S NUM = NUM + 1 


5 IF NUM .LT. 11 THEN GOTO LOOP 


In this example, you use the GOTO command in a loop that executes a 
Specified number of times. The first line in the procedure sets up a 
counter named NUM. The loop increases the value of the counter, does 
some processing and then tests the counter’s value. The command 
procedure exits from the loop when the value of NUM is greater than or 
equal to ll. 
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You can use the GOTO command in loops that prompt the user to indicate 
whether execution should continue. During each iteration of the loop, 
the procedure prompts for input data or a value for a variable. For 
example: 


S LOOP: 

S INQUIRE FILE "Filename" 

S IF FILE .EQS. "" THEN GOTO SKIP 
. GOTO LOOP 

S SKIP: 


In this example, the INQUIRE command requests a file name. If the 
user’s response is a null value, the loop does not execute. 
Otherwise, the loop executes iteratively until the user enters a null 
value by pressing only the RETURN key. 


Nesting Command Procedures 


The GOTO command described in the previous section provides one way to 
divide command procedures into more easily read and understood 
sections. In a more complex procedure, however, you may want to 
separate different sections into several smaller procedures. Or you 
may find it convenient to develop small, generalized procedures that 
perform common functions and then invoke these procedures from other 
procedures that you write. You can call one command procedure from 
inside another by using the @ command. Using the @ command to invoke 
new levels of command execution is similar to using a CALL statement 
in a high-level programming language. 


When you enter a procedure, the command level increases by one. For 
instance, if you invoke procedure SUB from interactive command level 
(level 0), SUB executes at command level 1. If SUB then calls SUBI, 
which calls SUBSB1l, SUB1 executes at command level 2 and SUBSB1 at 
command level 3. The deepest permissible command level is 13. 


By convention, the interactive level is the highest command level; and 
command level 13 the lowest. Therefore, if you move from command 
level 3 to command level 2, you move to the next higher command level. 


Figure 7- 
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1 shows the flow of control when you execute nested command 


procedures; the figure also shows how DCL creates new command levels 


when you 


command 
level 0 


execute nested command procedures. 


command command command 
level 1 level 2 level 3 
ccc ttt eee SUB .COM 
-4 S$ first command 
| S$ second command 
| S CSUR! ssf2cecese se = SUB1.COM 
| S . a 4 S first command 
| =) | S$ second command 
| S , | S @SUBSBl ------- 3 SUBSB1.COM 
- ee eee 5. EXIT | S . “-----; S first command 
| S | S second command 
| S ; | S 
wee ee eee eee S$ EXIT | S ; 
- ee ee S EXIT 


Figure 7-l: Command Levels in Nested Command Procedures 


If you need to pass information from one command level to another, use 
one of the following techniques: 


0 


Passing parameters -- You can pass up to eight parameters to 
a procedure you invoke using the @ command. See Chapter 5 
for a description of techniques for passing parameters. 


Using global symbols -- You can use global symbols to pass 
data from one procedure to another; a global symbol defined 
in a nested command procedure can be referred to in all 
command procedures. See Chapter 2 for a description of 
global symbols. 


Using data files -- You can write data to a data file using 
the WRITE command, then read the data back in a nested 
command procedure using the READ command. See Chapter 6 for 
information on writing and reading files. 
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Exiting from a Command Procedure 


A command procedure exits when it reaches the end of the procedure, an 
EXIT command, or a STOP command. If the exit is caused by the end of 
the procedure or an EXIT command, control returns to the next higher 
command level. For instance, if you invoke SUB at interactive command 
level, and SUB calls SUB1, then: 


Oo Exiting from SUB1 returns you to SUB at the command line 
following the call to SUBI1. 


o Exiting from SUB returns you to interactive command level. 


When you use the EXIT command to cause an exit, you can return a 
status value to the next higher command level by specifying the value 
as the parameter of the EXIT command. This status value is placed in 
the global symbols SSTATUS and SSEVERITY. Upon returning from the 
lower level routine, the higher level procedure performs any error 
handling based on its ON...THEN setting and the value of SSEVERITY. 
See Chapter 8 for a description of error handling in command 
procedures. 


If the STOP command causes the exit, control immediately returns to 
interactive command level. 


The following sections describe the EXIT and STOP commands in greater 
detail. 


The EXIT Command 


The EXIT command ends a command procedure and returns control to the 
next higher command level. 
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Command Parameters 
status-code 


A numeric expression that defines a value for the reserved global 
symbols SSTATUS and SSEVERITY. Note that the reserved global 
symbol SSEVERITY is affected by the value placed in the SSTATUS 
symbol. You can specify the status-code as an integer or an 
expression. If you do not specify a status-code, DCL does not 
change the values of SSTATUS and SSEVERITY from the most recently 
executed command or program. See Chapter 8 for a complete 
description of the SSTATUS and SSEVERITY symbols. 


You can use the EXIT command to make sure that a procedure does not 
execute certain lines. For example, if you write an error-handling 
routine at the end of a procedure, you can place an EXIT command 
before the routine: 


S EXIT ! End of normal execution path 
S ERROR: 


The EXIT command is also useful in procedures that have more than one 
execution path. For example: 


S START: 

S IF Pl J.EOS. "TAPE" .OR. Pl .EQS. "DISK" THEN GOTO ’Pl’ 
iS INQUIRE Pl "Enter device (TAPE or DISK)" 

S GOTO START 


S TAPE: ! Process tape files 
S EXIT 
S DISK: ! Process disk files 


> EXIT 


To execute this command procedure, you must enter either TAPE or DISK 
aS a parameter. The IF command uses a logical OR to test if either of 
these strings was entered. The GOTO command branches appropriately, 
using the parameter as the branch label. If Pl is not TAPE or DISK, 
the INQUIRE command prompts for a correct parameter; the GOTO START 
command establishes a loop. 
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The commands after the labels TAPE and DISK provide different paths 
through the procedure. The EXIT command before the label DISK ensures 
that the commands after the label DISK are not executed unless the 
procedure explicitly branches to DISK. 


Note that the EXIT command at the end of the procedure is not required 
because an implicit exit occurs when DCL detects the end-of-file 
(EOF). However, DIGITAL recommends that you use the EXIT command at 
the end of a command procedure. 


When a command procedure has multiple levels of interaction, you can 
use the EXIT command to pass status values from nested levels back to 
the calling procedure. The exit code defines values for the reserved 
global symbols SSTATUS and SSEVERITY. 

For example, suppose the procedure A.COM contains these lines: 


S @B 
S IF SSTATUS .EQ. 2 THEN GOTO CONTROL 


In addition, the procedure B.COM contains the line: 
S EXIT 2 


This EXIT command places the value 2 in the global symbols SSTATUS and 
SSEVERITY. The calling procedure, A.COM, tests SSTATUS. 


The STOP Command 


The STOP command ends a command procedure and immediately returns 
control to the interactive level, thus terminating any intermediate 
command procedures. 


Controlling Execution Flow in Command Procedures 


The following example uses the STOP command: 


S$ ON ERROR THEN GOTO OPEN_ERROR 
S$ OPEN 2 FILE/READ 


S OPEN_ERROR: 
3 WRITE 0 "Error opening file" 
S STOP 


In this command procedure, if an error occurs while attempting to open 
a file, the procedure goes to the label OPEN_ERROR, prints a message, 
Stops executing, and returns immediately to the interactive level. 


Chapter 8 


Controlling Error Conditions and CTRL/C Interrupts 


This chapter describes how to control command procedure execution when 
an error condition or a CTRL/C interrupt occurs. An error condition 
occurs when a command does not terminate successfully. A CTRL/C 
interrupt is the result of pressing CTRL/C during command procedure 
execution. 


Error Condition Handling 


Error conditions are stored as codes in the reserved global symbol 
SSTATUS. If an EXIT command does not explicitly set a value for 
SSTATUS, then DCL returns its current value. This value is set 
implicitly by individual commands and programs that execute in a 
procedure. The value that is set, called a condition code, provides 
information about the execution of: 


o The most recent command 
o The most recent program 
o The most recent procedure 
The following sections describe how you can include action routines 


and error handling statements in your procedures based on values in 
SSTATUS. 


SSTATUS and $SEVERITY Symbols 


DCL reserves two global symbols, SSTATUS and SSEVERITY, to maintain an 
error condition code called "exit status." 


The lowest three bits of the SSTATUS value represent the severity of 


the exit status. The remaining bits of the SSTATUS value are 
reserved, and are currently undefined. The SSEVERITY symbol contains 
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the same value as the lowest three bits of the SSTATUS value. 


DIGITAL recommends that you test severity values using the SSEVERITY 
Symbol instead of the SSTATUS symbol. This lets you avoid unnecessary 
modifications in the future, if other bits in SSTATUS are defined. 


Table 8-1 lists the severity values and their meanings. 


Table 8-l: Severity Values 


| | 
WARNING | This condition indicates that an operation | 
| completed, but not necessarily as expected. | 
| For example, if you try to mount a disk | 
| initialized read-only using the /WRITE | 
| qualifier, the following warning message | 
| appears: | 
| | 
| Disk is mounted read-only | 
| | 
| | 
| | 


RSTS/E prefixes all WARNING messages with 
the percent sign (%) character. 


| | 
| This condition indicates that an operation | 
| completed successfully, that is, with no | 
| errors or warnings. Informational or action | 
| messages also receive this status value. | 


| | 
| This condition indicates that an operation | 
| Gid not complete. For example, an ERROR | 
| message appears after you enter an illegal | 
| command or after you enter a command using | 
| invalid syntax. | 
| | 
| | 
| | 


RSTS/E prefixes all ERROR messages with the 
question mark (?) character. 


| | 
SEVERE_ERROR | This condition indicates that an operation | 
| did not complete, but for more serious | 
| reasons. | 
| | 
| RSTS/E prefixes all SEVERE ERROR messages | 
| with double question marks (??). | 


Controlling Error Conditions and CTRL/C Interrupts 


Note that the success code has an odd numeric value, while warning and 
error codes have even numeric values. Because DCL evaluates all odd 
values as true (1) and all even values as false (0), you can use the 
IF command to test the severity codes and determine if an operation 
completed successfully. For example: 


S IF SSEVERITY THEN 


This IF command executes the command after the THEN clause when the 
severity value is odd, indicating success. 


S IF .NOT. SSEVERITY THEN 
This IF command executes the command after the THEN clause if the 
severity value is even, indicating that a warning, error, or severe 
error occurred. 


Note 


The following DCL commands, if they complete 
successfully, do not affect the SSTATUS or SSEVERITY 


setting: 

o GOTO 
o STOP 
Oo SEOD 
o IF 


Oo SHOW SYMBOL 
o ON (See the next section for more information) 


Oo an aSSignment statement 
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The ON Command 


By default, DCL performs an EXIT command when an error or severe error 
occurs and continues processing when a warning occurs. You can 
override this default with the ON command. 


The ON command specifies an action to be performed whenever DCL 
detects a warning, error, or severe error in a command procedure. 
Whenever a command, program, or command procedure completes, DCL 
checks the exit status and takes action based on the current setting 
of the ON command. 


| Format | 


| ON severity-level THEN command | 


Command Parameters 
severity-level 


Specifies the severity level at which to perform the command 
action. You can specify one of the following severity-level 
keywords: 


Oo WARNING 
O ERROR 


© SEVERE_ERROR 


command 


Specifies the CCL or DCL command to be executed if the status 
code returned from the last command, program, or command 
procedure is greater than or equal to the severity level you 
specify. You can specify any valid CCL or DCL command after the 
THEN keyword, optionally prefixed with a $ character. 


When DCL finds an ON command, it stores the command following the THEN 
keyword in a special area of the local symbol table and executes it 
whenever an error greater than or equal to the specified severity 
level occurs. 
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If you define an ON command action for a specific severity level, DCL 
performs the specified action when errors of the same or worse 
severity occur. When less severe errors occur, DCL continues to 
process the file. 


Table 8-2 summarizes how the ON command controls error handling. 


Table 8-2: ON Command Keywords and Actions 


Se fer ee ee ee ee ee ee ee ee ee + 
| ON Keyword | Action Taken | 
toe r eee ee ee ee ee fore rr ee ee ee ee ee ee ee ee ee ee ee ee eee + 
| | | | 
| WARNING | Command procedure performs the specified action if | 
| | a warning, error, or severe error occurs. | 
Se fer re ee ee ee ee ee ee ee ee eee + 


an error or severe error occurs; the - procedure 


| | 
ERROR | Command procedure performs the specified action if | 
| | 

| continues if a warning occurs. | 


| Command procedure performs the specified action if | 
| a severe error occurs; the procedure continues if a | 
| warning or error occurs. | 


For example, if you want a command procedure to exit whenever a 
warning, error, or severe error occurs, use the command: 


S ON WARNING THEN EXIT 


If you want the command procedure to continue if a warning or an error 
occurs, but to branch to another part of the file if a severe error 
occurs, use a command such as: 


S$ ON SEVERE ERROR THEN GOTO ERROR_TRAP 


This ON command requests that the procedure branch to the label 
ERROR_TRAP only in the case of a severe error. If any command in the 
procedure causes a warning or error condition, execution continues 
with the next command in the procedure. 


Note that severe errors always cause the command following the THEN 
keyword to be executed, regardless of the severity level you specify 
in the ON command. You must disable error checking with the SET NOON 
command for processing to continue when a severe error occurs. 


When DCL executes the command following the THEN keyword, it resets 
the ON setting to its default (ON ERROR THEN EXIT). For example: 


S$ ON WARNING THEN GOTO ERROR_TRAP 
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In this example, if a warning occurs in the command procedure then 
control passes to the first command following the label ERROR_TRAP, 
and the ON setting is reset to ON ERROR THEN EXIT. If you want to 
restore the previous ON setting, you must reissue the ON WARNING THEN 
GOTO ERROR_TRAP command. 


The action specified by an ON command applies only within the command 
procedure in which the command is executed. Therefore, if you execute 
an ON command in a procedure that invokes another procedure, the ON 
command action does not apply to the nested procedure. 


Enabling and Disabling Error Checking 


The SET NOON command lets you override default error checking. You 
can use SET NOON to tell DCL not to check the status code returned 
from the last command, program, or command procedure executed. 


| Format | 


| SET [NO]ON | 


During command procedure execution, DCL normally checks the status 
code returned when a command, program, or command procedure completes, 
and saves the numeric value of this code in the reserved global symbol 
SSTATUS. The low-order three bits of this value are also saved in the 
reserved global symbol SSEVERITY. 


When SET NOON is in effect, DCL continues to place the status code 
value in SSTATUS and the severity level in SSEVERITY, but does not 
perform any action based on the value. As a result, the command 
procedure continues to execute regardless of how many errors are 
returned. 


Like SET ON, the SET NOON command applies only at the current command 
level. If you use the SET NOON command in a command procedure that 
executes another procedure, DCL establishes the default, SET ON, while 
the second procedure executes. 
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The following example uses the SET NOON and SET ON commands: 


S ON WARNING THEN EXIT 
S SET NOON 
S MOUNT MMO: 


S SET ON 


In this example, you temporarily disable error checking and attempt to 
mount a tape. If any error occurs, processing continues. The SET ON 
command restores the current setting of the ON command; that is, the 
procedure exits if later warnings, errors, or severe errors occur. 


Note 


Whenever an input error other than EOF occurs when 
reading from a command file, DCL displays an error 
message, generates a SEVERE ERROR, and terminates the 
command procedure. DCL takes this action regardless 
of the current ON setting or severity level. 


CTRL/C Interrupt Handling 


You can design a command procedure so that DCL takes a certain course 
of action when the user presses CTRL/C during execution of the 
procedure. 


When the user presses CTRL/C at a logged-in terminal, the RSTS/E 
terminal service routine sets a CTRL/C event flag. DCL initially 
clears this flag when a user logs in to the system. Once the CTRL/C 
Flag is set, it remains set until examined by a monitor directive, 
which clears the flag automatically. This design lets DCL read the 
CTRL/C event flag to determine if a CTRL/C interrupt occurs during 
command procedure execution. 


If you execute a program within a command procedure that is designed 
to abort or to perform clean-up operations and then abort when you 
press CTRL/C, the CTRL/C event flag remains set and DCL takes action 
based on the ON CONTROL_C setting. 


Some programs (Such as MAIL), however, are designed to continue to 
operate properly when the user presses CTRL/C. In this case, DCL will 
take CTRL/C action when the program exits. Because this may not be 
desirable, make sure that the event flag remains clear by issuing the 
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SET NOCONTROL=C command to disable CTRL/C checking before you execute 
the program. Then, after the program executes, you can issue the SET 
CONTROL=C command to reenable checking. 


In addition, you can completely disable a terminal’s CTRL/C key by 
uSing the SET TERMINAL/NOCONTROL=C command. 


Note 


You should use the SET NOCONTROL=C and SET 

TERMINAL/NOCONTROL=C commands for special applications 
that have been thoroughly tested. Generally, DIGITAL 
does not recommend that you disable CTRL/C interrupts. 


For example, if a procedure that disables CTRL/C 
interrupts begins to loop uncontrollably, you cannot 
gain control to stop the procedure from your terminal; 
you must use another terminal to terminate the 
procedure or you must request the system manager to 
terminate it for you. 


The following sections describe how to establish a CTRL/C action 
routine, and how to enable or disable CTRL/C checking. 


Setting a CTRL/C Action Routine 
The ON CONTROL _C command specifies the action to take when a CTRL/C 
interrupt occurs during execution of a command procedure. The 


specified action applies only within the command procedure in which 
the command is executed. 


Command Parameters 
command 
Specifies the DCL or CCL command to be executed if a CTRL/C 


condition occurs. You can specify any valid DCL or CCL command 
after the THEN keyword, optionally prefixed with a $ character. 


Using the standard rules of substitution, DCL first performs a syntax 
check and substitutes any symbol value following the THEN clause. DCL 


8-8 


Controlling Error Conditions and CTRL/C Interrupts 
then stores the command in a special area of the local symbol table 
and executes it whenever a CTRL/C interrupt occurs. 

The following example shows the use of ON CONTROL C: 


S$ ON CONTROL_C THEN GOTO CTRL_EXIT 


CTRL_EXIT: 
CLOSE. 4 
CLOSE 2 
EXIT 


Ut YU Ur 


When a CTRL/C interrupt occurs during execution of this procedure, DCL 
executes the GOTO command, which transfers control to the line labeled 
CTRL_EXIT:. At this label, the procedure performs clean-up 
Operations. In this example, clean-up consists of closing files 
opened on channels 1 and 2, and exiting. 


When you do not specify a CTRL/C action routine and a CTRL/C interrupt 
occurs, DCL executes an EXIT command by default and returns control to 
the next higher-level command procedure. Because control returns with 
the CTRL/C event flag still set, the higher-level procedure takes 
whatever action you specify for CTRL/C handling at that level. 


When you do specify a CTRL/C action routine, anytime DCL takes a 
CTRL/C action, the default setting (ON CONTROL C THEN EXIT) is 
reinitialized in the current procedure. Therefore, to establish a 
setting other than the default, the procedure must reexecute the ON 
CONTROL _C command after a CTRL/C interrupt occurs. 


Disabling and Reenabling CTRL/C Interruptions 


The SET NOCONTROL=C command disables CTRL/C checking by DCL within. a 
command procedure. That is, if a command procedure executes the SET 
NOCONTROL=C command, pressing CTRL/C will not cause the ON CONTROL _C 
command to be executed. Pressing CTRL/C will still have its normal 
effect on running programs (unless a SET TERMINAL/NOCONTROL=C command 
is in effect). 


On the other hand, the SET CONTROL=C command reenables CTRL/C 
Checking. THE SET [NO]JCONTROL=C setting applies only at the current 
command level. 


Controlling Error Conditions and CTRL/C Interrupts 


Use the SET NOCONTROL=C command in procedures where you do not want 
DCL to take special action if a CTRL/C interrupt occurs. For example: 


SET NOCONTROL=C 
RUN PROGI1 
SET CONTROL=C 


Ut i 


In this example, the command procedure executes a program, which could 
generate a CTRL/C condition. You issue the SET NOCONTROL=C command, 
execute the program, and then reenable CTRL/C checking with the SET 
CONTROL=C command. | 
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Controlling Terminal Output 


RSTS/E provides the following ways to enable and disable command line 
display and program output to your terminal during its execution of a 
command procedure: 


o SET ECHO command 

o SET VERIFY command 

o Terminal logging commands 
You can use these commands interactively or within a command 
procedure. However, they only affect output to your terminal when a 
command procedure is executing. 
By default, RSTS/E displays all output except DCL command lines during 
command procedure execution. However, you may sometimes want to 


disable all terminal output for "silent" command procedure processing, 
or to enable command line display to help debug a command procedure. 


SET [NO]ECHO Command 
You use the SET ECHO and SET NOECHO commands when you want to enable 


and disable the display of all output from a command procedure on your 
terminal. 


Format 
SET [NO]ECHO 


Command Qualifiers Defaults 


/[NO]WARNINGS /WARNINGS 
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Command Qualifiers 


/{NO]WARNINGS 


Specifies whether warnings and error messages display on the 


terminal. You can use this qualifier only with the SET NOECHO 
command. | 


When ECHO is in effect, RSTS/E displays the following during command 
procedure execution: 


o All program data written to or echoed on the terminal 
o Warnings and error messages 


o DCL command lines if SET VERIFY is in effect (see the 


following section for a description of the SET [NO]VERIFY 
command ) 


When you first log in to the system, ECHO is in effect. You can issue 
the SET ECHO or SET NOECHO command either at the interactive level or 
within a command procedure to change its setting. The [NO]ECHO 
setting is global to all command procedures and remains in effect 


until you change it. 


When NOECHO is in effect, RSTS/E displays only the following: 


Oo Warnings and error messages (unless you specify the 
/NOWARNINGS qualifier) 


o Messages broadcast to your terminal 

o Prompts from an INQUIRE command 

o Data output with the WRITE 0 command 
RSTS/E suppresses all DCL command lines and other program data written 
to the terminal when NOECHO is in effect. If you specify the 
/NOWARNINGS qualifier with the SET NOECHO command, then warnings and 


error messages also do not display. 


Note that NOECHO overrides the [NO]VERIFY setting, described in the 
next section. 
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SET [NO]VERIFY Command 


You use the SET VERIFY and SET NOVERIFY commands when you want to 
enable and disable the display of all DCL command lines as they occur 
during command procedure execution. See Chapter 2 for a complete 
description of the SET [NO])VERIFY command. 


SET [NO]VERIFY also controls whether RSTS/E writes the command lines 
to a log file. See the next section for a complete description of the 
terminal logging feature. 


If SET VERIFY is in effect, command lines are displayed exactly as 
they appear in the procedure, before any substitution has been 
performed. You can specify the /DEBUG qualifier to display the 
command line as it appears after substitution. 


When you first log in to the system, NOVERIFY is in effect. You can 
issue the SET VERIFY or SET NOVERIFY command either at the interactive 
level or within a command procedure to change its setting. The 
[NO]VERIFY setting is global to all command procedures and remains in 
effect until you change it. 


When NOECHO is in effect (see the previous section), command lines are 
not displayed at the terminal, regardless of the VERIFY setting. 
However, if VERIFY is in effect and a log file is open (see the next 
section), RSTS/E continues to write the command lines to the log file. 


Creating a Log File of a Terminal Session 
The terminal logging feature lets you create and use a terminal log 
file to save a copy of the output that appears during the execution of 
a command procedure. See the RSTS/E System User’s Guide for a 
complete description, with examples, of terminal logging. 
Note that if you enable a log file during execution of a command 
procedure, the SET NOVERIFY command (see the previous section) 
disables output of command lines both to the terminal and to the log 
file. 
The following sections describe the commands that you use to: 

o Open a terminal log file 


o Close a terminal log file 


o Selectively disable and enable output to the log file 
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OPEN/LOG_FILE 


The OPEN/LOG FILE command opens a disk file for terminal logging. You 
can issue the OPEN/LOG_ FILE command either interactively or within a 
command procedure. 


You can only open one log file at any given time. If a log file is 
already open when you attempt to open a second log file, RSTS/E issues 


an error message and does not open the second file; instead, the 
current log file remains open. 


Format 


OPEN/LOG_FILE file-spec 


Command Qualifiers Defaults 
/APPEND See discussion 
/DISABLE /ENABLE 
/ENABLE /ENABLE 
/{NO]REPLACE See discussion 
/{[NO]TIME STAMP /NOTIME STAMP 
Prompts 


File: file-spec 


Command Parameters 
file-spec 


Specifies the disk file to open for logging terminal output. 
RSTS/E displays an error message if you specify a nondisk file, 
or if the file-spec is invalid. RSTS/E also displays an error 
message if a log file is already open. If you do not specify a 
file type, RSTS/E assumes a file type of .LOG. Unless you 
include the /APPEND qualifier, RSTS/E opens the file for output, 
and deletes any existing file of the same name. 


Command Qualifiers 

/APPEND 
Tells RSTS/E to add data to the end of the file you specify. 
This qualifier lets you append terminal output to the end of an 


existing log file. If the file you specify does not exist, then 
RSTS/E ignores this qualifier and opens a new file. Note that 
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only RSTS/E stream ASCII files can be appended: if you specify a 
file that has RMS attributes, an error message displays. 


/DISABLE 


Indicates that terminal output should not be logged to the file 
until you issue the SET LOG FILE/ENABLE command to enable 
terminal logging. 


/ENABLE 


Indicates that output should be logged to the file. This 
qualifier is the default when you issue the OPEN/LOG_FILE 
command. 


/{NO]REPLACE 


Specifies whether to replace an existing file with a new file. 
If the log file that you specify already exists: 


Oo  /REPLACE tells RSTS/E to delete the existing file and create 
a new file. 


o /NOREPLACE tells RSTS/E not to replace the file if it exists; 
in this case, an error message displays. 


If you specify neither qualifier, then RSTS/E issues a warning 
message and asks if you want to replace the file. 


Note that the /[NO]REPLACE qualifier conflicts with the /APPEND 
qualifier. 


/{NO]TIME_STAMP 


Indicates whether to prefix each line in the log file with a 
date/time stamp. The default is /NOTIME_STAMP. However, if you 
specify /TIME_STAMP, RSTS/E prefixes each line in the log file 
with a date/time stamp specifying the date and time that the line 
was copied to the log file. Note that the date and time format 
is based on the system defaults that your system manager 
establishes. The date/time fields occupy the first 22 characters 
of each line. 
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CLOSE/LOG_FILE 


The CLOSE/LOG_FILE command closes a log file that you opened with the 
OPEN/LOG_FILE command. 


Use the CLOSE/LOG_ FILE command to close an open log file either during 
a session at your terminal or within a command procedure. 


If logging is enabled when you issue the CLOSE/LOG_FILE command, then 
RSTS/E writes the command itself to the log file before closing it. ares 
If no log file is open when you issue this command, then RSTS/E 
displays an error message. 


SET LOG_FILE 
After you open a log file, you can use the SET LOG FILE command to 


selectively enable and disable logging to the file. You can also use 
this command to enable or disable the time stamp feature in the log. 


Format 


SET LOG FILE 


/DISABLE 
/ENABLE 
/{NO])TIME STAMP 


| 
| 
| 
| 
| Command Qualifiers Defaults 
| 
| 
| 
| 


Command Qualifiers 
/DISABLE 


Indicates that terminal or command file output should not be 
logged to the current log file. If logging is currently 
disabled, then RSTS/E ignores this qualifier. This qualifier 
conflicts with /ENABLE. 
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/ ENABLE 


Indicates that terminal or command file output to the log file 
Should be enabled. If logging is currently enabled, then RSTS/E 
ignores this qualifier. This qualifier conflicts with /DISABLE. 


/{NO]TIME STAMP 
Enables or disables the time stamp feature, which prefixes each 


line in the log file with a date/time stamp in a format that the 
system manager has defined. 
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Sample Command Procedures 


The following sample command procedures demonstrate some of the 
concepts and techniques that this manual discusses. 


In the following example, the command procedure remembers the most 
recent file you edited, and automatically places it in the editor when 
you type the EDIT command: 
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EDIT.COM - Command file to "remember" last file edited 


Parameters: 
Pl - file to edit, or null to edit last file edited 


To take full advantage of this command file, add the 
following global command to your LOGIN.COM file 


S EDIT == "@EDIT" 

Then, you edit a file in the usual way: 
S EDIT filespec 

To edit the file you last edited, simply type: 
S$ EDIT 


The last file edited is maintained in the global 
symbol LAST EDIT. 


_IF FSTYPE(LAST_EDIT) .EQS. "UNDEFINED" THEN LAST_EDIT == "" 
_IF FSLENGTH(P1) .EQ. 0 THEN Pl = LAST_EDIT 


GETPFIL: 


_IF FSLENGTH(P1) .EQ. 0 THEN _INQUIRE/EXIT=GETFIL Pl "File" 
_IF FSLENGTH(P1) .EQ. 0 THEN GOTO GETFIL 


LAST EDIT == Pl 
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_SET NODATA 
WRITE 0: “Editing file" {LAST EDIT)..." 
_EDIT ‘LAST EDIT! 

_SET DATA 
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In the following example, the command procedure searches for and reads 
files specified with wildcards: 


S ! READ.COM - Command file to EDIT/READ wildcard file-specs 

Ss. 

S ! Parameters: 

S ! Pl - wildcard filespec (prompt if null) 

i! 

S _SET NODATA 

S _IF Pl .EQS. "" THEN INQUIRE/EXIT=END Pl "Filespec to read" 
S Pl = FSEDIT(P1,-1) 

S NEXT FILE = FSSEARCH(P1) 

SLOOP: 

S _IF NEXT FILE .EQS. "" THEN EXIT 

S _INQUIRE/EXIT=END Pl "Read ’'NEXT_FILE’ <yes>" 

S iF Pl. .BOS. “" THEN Pl. = "YES" 

S Pl = FSEDIT(P1,-1) 

S _IF FSINSTR(1,"YES",P1) .EQ. 1 THEN _EDIT/READ 'NEXT_ FILE’ 
= NEXT FILE = FSSEARCH( ) 

S _GOTO LOOP 

SEND: 


In the following example, the command procedure remembers command 
arguments: 


- 


MEMCOM - Remember previous arguments for commands 


Parameters: 
Pl Name of command to use 
P2 - P8 Arguments of command to be remembered 


Description: 
This procedure remembers its arguments and allows them 
to be used again if desired. It also understands wild cards 
if they are the first argument to the command (i.e. P2). 
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Parameter Pl is the name of a DCL or CCL command such as EDT. 
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This procedure uses a DCL global variable of the form 
’Command’ Memory where '’Command’ is the name of the command 
to remember the arguments for each command. 


If P2 is a wildcard filespec then MEMCOM will find the first 
(Or next) occurrence and prompt with the file found as the 
default. To accept the file type RETURN. To see the next 
file type CONTROL/Z. To quit type CONTROL/C. 


Examples: 
S E-DT :== @MEMCOM EDT 
S EDT *.COM 

Or 
S TY-PE := @MEMCOM TYPE 
S TYPE *.B?S 


TART: 


WILD = 0 ! Initialize wild flag 


Set command name. If no command is present then write an error 
message (which will trigger default ON ERROR THEN EXIT action). 


COMMAND = Pl 
_IF COMMAND .EQS. "" THEN WRITE 0 "?MEMCOM - No command present" 


If command memory is undefined then set it to "" 


_IF FSTYPE(’COMMAND’ MEMORY) .EQS. "UNDEFINED" THEN - 
‘COMMAND’ MEMORY == "" 


Assume second argument is a file name and save it. If a file name 
was specified then go process it. 


FILE = P2 
_IF FILE .NES. "" THEN GOTO PARSE FILE 
No file name was given. If something was saved in command memory 


then ask if it is to be used again; otherwise, just ask for 
a file name. 


MEMORY = ‘COMMAND’ MEMORY 

_IF MEMORY .EQS. "" THEN _GOTO ASK 
_INQUIRE/EXIT=NEXT FILE "FILE <'’’MEMORY’>" 
_IF FILE .EQS. "" THEN FILE = MEMORY 
_GOTO PARSE FILE 


Ask for a file spec if none was given on the command line and none 
was saved in command memory 


ASK: 


_INQUIRE/EXIT=EXIT FILE "FILE" 
_IF FILE .EQS. "" THEN _GOTO ASK 
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This section parses the file spec. It separates any switches, 
constructs an argument list, and checks the file spec for wildcards. 
After the argument list is constructed it is saved in the 

command memory. 


PARSE FILE: 


POS = FSINSTR(1,FILE,"/") 

SWITCH = "" 

_IF POS .NE. 0 THEN SWITCH = FSRIGHT(FILE, POS) 
FILE = FSPARSE( FILE) 


ARGS. = FILE’ "“SWITCH’.*P3* "Pd" ©p5" PO" "PT" “Ps? 
_IF ARGS .NES. "" THEN ‘COMMAND’ MEMORY == ARGS 
WILD = (FSPARSE(FILE,,"FLAGS") .AND. 870) .NE. 0 


_IF .NOT. WILD THEN _GOTO DOIT 
NEXT FILE = FSSEARCH(FILE) 


If the file spec was wildcard then ask for confirmation of any 
file that matches the wild card. If the user accepted the default 
then construct the arg list with the next file. 


ASK WILD: 


_INQUIRE/EXIT=NEXT FILE "FILE <’’NEXT_FILE’>" 

_IF FILE .NES. "" THEN GOTO PARSE FILE 

FILE = NEXT FILE 

ARGS := 'FILE’ ‘SWITCH’ 'P3'’ 'P4'’ 'P5'’ 'P6’ 'P7! 'PB! 


At last. Invoke the command on the constructed arg list 


DOIT: 


_SET NODATA 
COMMAND’ ‘ARGS’ 
_SET DATA 


If it was a wildcard file spec then get the next file and 
process it too. 


NEXT: 


NEXT FILE = "" 
_IF WILD THEN NEXT_FILE = FSSEARCH( ) 


_IF NEXT FILE .NES. "" THEN GOTO ASK_WILD 


All done. Clean up and exit 


BALT 


VERIFY = FSVERIFY(VERIFY) 
_EXIT 
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RSTS/E and VAX/VMS Command Processor Differences 


Chapter 2 notes that it is desirable, where possible, to provide 
compatibility between RSTS/E and VAX/VMS. This helps customers who 
use both operating systems, as well as those who will migrate to VAX 
systems in the future. Since RSTS/E and VMS have many inherent 
differences, complete compatibility between the two systems is neither 
desirable nor possible. 


This appendix lists some of the major differences between the RSTS/E 
and VMS command processors: 


o Character substring replacement -- RSTS/E does not support 
the VMS substring assignment feature: 


symbol-name[offset,size] :=[=]) string-value 


o Arithmetic overlays -- RSTS/E does not support the VMS binary 
overlay feature: 
symbol-name[bit-position,size] = expression 
o Exit status values -- RSTS/E recognizes only the following 


exit status values: 


0 (Warning) 

1 (Success) 

2 (Error) 

4 (Severe error) 


Note that RSTS/E does not support the VMS exit status value 3 
(information). 


o Symbol substitution -- RSTS/E only supports the apostrophe 
character as a substitution operator. RSTS/E does not 
Support the VMS ampersand substitution operator. Users who 
need the ’multi-level’ substitution feature provided by the 
ampersand operator can issue multiple assignments to produce 
the same result. 
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o Symbol name abbreviations -- In order to maintain 
compatibility with other commands, RSTS/E uses the hyphen (-) 
character to identify a symbol name’s minimum abbreviation. 
RSTS/E also accepts the VMS abbreviation character (*). 


o RSTS/E accepts abbreviations for all command synonyms and 


functions. 

o String operators -- RSTS/E only supports the string 
concatenation operator, not the string reduction operator. 

o Symbol tables -- RSTS/E does not define local symbols at the 
interactive level. If a local symbol assignment is attempted 


at the interactive level, DCL places the symbol in the global 
symbol table. If a command that accepts the /GLOBAL and 
/LOCAL qualifiers is issued with /LOCAL at the interactive 
level, DCL issues an error message. 


o Symbol table searching -- VMS performs symbol searching by 
first searching the local symbol table at the current command 
level, then searching each higher command level’s local 
symbol table, and then finally searching the global symbol 
table. RSTS/E first searches the local symbol table at the 
current command level, then the global symbol table. No 
higher-level local symbol tables are searched. 


o VMS String Functions -- Since many RSTS/E users make use of 
BASIC-PLUS as a programming language, the DCL string handling 
functions on RSTS/E are compatible with BASIC-PLUS string 
functions. Use of the VMS string functions would cause 
unnecessary confusion for RSTS/E users, Since the VMS 
functions use (0-based) offset arguments, rather than 
(l-based) position arguments. 


The following list outlines the RSTS/E string handling 
functions and the corresponding VMS function: 


RSTS/E Function VMS Function 
FSASCII (none) 
FSCHR (none) 
FSCVTIME FSCVTIME 
FSEDIT (none) 
FSINSTR FSLOCATE 
FSLEFT (none) 
FSLENGTH FSLENGTH 
FSMID FSEXTRACT 
FSRIGHT (none) 
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DCL Files -- VMS uses a logical name as the means for 
referencing an open file with the READ, WRITE and CLOSE 
commands. Furthermore, VMS makes use of standard logicals to 
refer to the input, command and output devices (SYSSINPUT, 
SYSSCOMMAND, and SYSSOUTPUT). RSTS/E uses a channel number 
to reference files opened with the OPEN command. This 
technique lends itself more naturally to the file access 
mechanisms used in BASIC-PLUS. 
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RSTS/E Error Messages 


Table C-1 lists RSTS/E error messages and their corresponding numeric 
values. 


Table C-l: RSTS/E Error Messages 


| Value | Full Error Text 


| | 

| | 2??Bad directory for device 
| | ?Illegal file name 

| | ?Account or device in use 

| | 2?No room for user on device 
| | 2?Can’t find file or account 
| | ?Not a valid device 

| | ?1/0 channel already open 

| | ?Device not available 

| | ?I1/0 channel not open 

| | ?Protection violation 

| | ?End of file on device 

| 12 | ??Fatal system I/O failure 
| | 

| | 

| | 

| | 

| | 

| | 

| | 

| | 

| | 

| | 

| | 

| | 

| | 


13 ?Data error on device 

14 ?Device hung or write locked 
15 ?Keyboard wait exhausted 

16 ?Name or account now exists 
17 ?Too many open files on unit 
18 ?Illegal SYS () usage 

19 ?Disk block is interlocked 
20 ?Pack IDs don’t match 

re! ?Disk pack is not mounted 

ae ?Disk pack is locked out 

a3 ?Illegal cluster size 

24 ?Disk pack is private 

a5 Disk pack needs REBUILDing 
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Table C-ls: 


| Value 


RSTS/E Error Messages (Cont. ) 


??Disk pack mount error 
?I/0 to detached keyboard 
Programmable “C trap 
??Unused error message 29 
?Device not file-structured 
?Illegal byte count for I/0 
?No buffer space available 
2?0dd address trap 
??Reserved instruction trap 
2?Memory management trap 
2?SP stack overflow 

2?Disk error during swap 
??Memory parity failure 
?Maptape select error 
?Maptape record length error 
2?Non-res run-time system 
?Virtual buffer too large 
?Virtual array not on disk 
?Matrix or array too big 
?Virtual array not yet open 
?Illegal I/O Channel 

?Line too long 

Floating point error 
sArgument too large in EXP 
¢Data format error 

sInteger error 

?Illegal number 

Illegal argument in LOG 
sImaginary square roots 
?Subscript out of range 
?Can’t invert matrix 

2?0ut of data 

2?ON statement out of range 
?Not enough data in record 
?Integer overflow, FOR loop 
SDivision by 0 

?No run-time system 

?FIELD overflows buffer 
?Not a random access device 
?Illegal MAGTAPE() usage 
?Missing special feature 
?Illegal switch usage 

?End of volume 

2?Quota exceeded 

??Unused error message 70 
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Table C-ls: 


| Value 


RSTS/E Error Messages 


RSTS/E Error Messages (Cont. ) 


| | 
| ?Statement not found | 
| ?PRETURN without GOSUB | 
| ?FNEND without function call | 
| ?Undefined function called | 
| ?Illegal symbol | 
| ?Illegal verb | 
| ?Illegal expression | 
| ?Illegal mode mixing | 
| ?Illegal IF statement | 
| ?Illegal conditional clause | 
| ?Illegal function name | 
| ?Illegal dummy variable | 
| ?Illegal FN redefinition | 
| ?Illegal line number(s) | 
| ?Modifier error | 
| ??Unused error message 86 | 
| ?PExpression too complicated | 
| ?Arguments don’t match | 
| ?Too many arguments | 
| Inconsistent function usage | 
| ?Illegal DEF nesting | 
| ?FOR without NEXT | 
| ?NEXT without FOR | 
| ?DEF without FNEND | 
| ?FNEND without DEF | 
| ?Literal string needed | 
| ?Too few arguments | 
; voyntax 1rror | 
| ?String is needed | 
| ?Number is needed | 
| ?Data type error | 
| ?1 or 2 dimensions only | 
| 2??Program lost-Sorry | 
| ?RESUME and no error | 
| ?Redimensioned array | 
| Inconsistent subscript use | 
| ?ON statement needs GOTO | 
| ?End of statement not seen | 
| ?What? | 
| ?Bad line number pair | 
| ?Not enough available memory | 
| ?Execute only file | 
| ?Please use the RUN command | 
| eCan’t CONTinue | 
| ?File exists-RENAME/REPLACE | 


C=3 


RSTS/E Error Messages 


Table C-ls: 


| Value 


RSTS/E Error Messages (Cont. ) 


?PRINT-USING format error 
?Matrix or array without DIM 
?Bad number in PRINT-USING 
?Illegal in immediate mode 
?PRINT-USING buffer overflow 
?Illegal statement 

?Illegal FIELD variable 

stop 

?Matrix dimension error 
?Wrong math package 
??Maximum memory exceeded 
SSCALE factor interlock 
?Tape records not ANSI 

2?Tape BOT detected 

?Key not changeable 

?No current record 

?Record has been deleted 
?Illegal usage for device 
?Duplicate key detected 
?Illegal usage | 
?Illegal or illogical access 
?Illegal key attributes 
?File is locked 

?Invalid file options 

?Index not initialized 
?Illegal operation 

?Illegal record on file 

?Bad record identifier 
?Invalid key of reference 
?Key size too large 

?Tape not ansi labeled 
?RECORD number exceeds max 
?Bad RECORDSIZE on OPEN 

?Not at end of file 

?No primary key specified 
?Key field beyond record end 
?Illogical record accessing 
?Record already exists 
?Record/bucket locked 
?Record not found 

?Size of record invalid 
?Record on file too big 
?Primary key out of sequence 
?Key larger than record 
?File attributes not matched 
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| Value 


RSTS/E Error Messages (Cont. ) 


Full Error Text 


?Move overflows buffer 
?Cannot open file 

2?No file name 

?Terminal fmt file required 
?Cannot position to EOF 
?Negative fill or string len 
?Illegal record format 
?Illegal ALLOW clause 
??Unused ERROR message 169 
?Indexed not fully optimized 
?RRV not fully updated 
?Record LOCK failed 
?Invalid RFA field 
?Unexpired file date 

?Node name error 

?Negative TAB not allowed 
?Too much data in record 
?OPEN Error - file corrupted 
??Unused ERROR message 179 
?No support for op in task 
Decimal overflow 

?Network operation rejected 
?REMAP overflows buffer 
?Unaligned REMAP variable 
ZRECORDSIZE overflows MAP 
?Improper error handling 
?Illegal record lock clause 
??Unused ERROR message 188 
??Unused ERROR message 189 
??Unused ERROR message 190 
??Unused ERROR message 191 
??Unused ERROR message 192 
??Unused ERROR message 193 
??Unused ERROR message 194 
??Unused ERROR message 195 
??Unused ERROR message 196 
??Unused ERROR message 197 
??Unused ERROR message 198 
??Unused ERROR message 199 
??Unused ERROR message 200 
??Unused ERROR message 201 
??Unused ERROR message 202 
??Unused ERROR message 203 
??Unused ERROR message 204 
??Unused ERROR message 205 
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RSTS/E Error Messages 


Table C-ls 


| Value 


RSTS/E Error Messages (Cont. ) 


2??Unused ERROR message 206 
??Unused ERROR message 207 
??Unused ERROR message 208 
??Unused ERROR message 209 
??Unused ERROR message 210 
2?Unused ERROR message 211 
??Unused ERROR message 212 
??Unused ERROR message 213 
??Unused ERROR message 214 
??Unused ERROR message 215 
??Unused ERROR message 216 
??Unused ERROR message 217 
??Unused ERROR message 218 
??Unused ERROR message 219 
??Unused ERROR message 220 
?2?Unused ERROR message 221 
??Unused ERROR message 222 
2?Unused ERROR message 223 
2??Unused ERROR message 224 
??Unused ERROR message 225 
??Unused ERROR message 226 
?String too long 
?RECORDTYPES not matched 
??Unused ERROR message 229 
?No fields in image 
?Illegal string image 
?Null image 

?ITllegal numeric image 
?Numeric image for string 
?String image for numeric 
?TIME limit exceeded 

?lst arg to SEQS > 2nd 
?Arrays must be same dim 
?Arrays must be square 
?Cannot change array dims 
?Floating overflow 
?Floating underflow 

?CHAIN to non-existent line 
?Exponentiation error 
?Illegal exit from DEF* 
?Error trap needs RESUME 
?Illegal RESUME to SUBR 
?Illegal subroutine return 
?Argument out of bounds 
?Not implemented 


RSTS/E Error Messages 


Table C-l: RSTS/E Error Messages (Cont. ) 


+---2¢------ tere ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee eee ee ee ee eee + 

| Decimal | | | 

| Value | Full Error Text | 

+--- +e eee tence ee eee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee eee + 
25 ?Recursive subroutine call 


| | | 
| | | 
| 252 | ?FILE ACP failure | 
| | | 
| | | 
| | | 


255 ?Directive error 
254 ??Unused ERROR message 254 
255 ??Unused ERROR message 255 
Sr tar er ee ee ee ee ee ee ee eee ee eee + 


Appendix D 


ASCII Character Codes 


Table D-1l1 lists all ASCII character codes. 


Table D-l: ASCII Character Codes 


+ eseeee exeeeeeeeeeeeeeeeseeeeeeeweeeeweeeeeeeweeeeeeenweeeweeeeeeeeeeeeeseeaeeeeeee «= 
| ASCII 

+--+ eee +------- fee eee ee ee eee pert ee ee ee ee ee eee ee ee ee eee ee eee 
| Decimal | Octal | Character | Remarks 

t--- ee eee t--- eee i Herre er ee ee ee ee eee eee 
| | | | 

| 0 | 000 | NUL | Null, FILL character 

| 1 | O01 | SOH | CTRL/A 

| 2 | 002 | STX | CTRL/B 

| 3 | 003 | ETX | CTRL/C 

| 4 | 004 | EOT | End of transmission, CTRL/D 

| 2 | 005 | ENQ | CTRL/E 

| 6 | 006 | ACK | CTRL/F 

| F | O07 | BEL | Bell, CTRL/G 

| 8 | 010 | BS | Backspace, CTRL/H 

| 9 | 011 | HT | Horizontal tab, CTRL/I 

| 10 | 012 | LF | Line feed, CTRL/J 

| 11 | 013 | VT | Vertical tab, CTRL/K 

| 12 | 014 | FF | Form feed, page, CTRL/L 

| Le |} O15 | CR | Carriage return, CTRL/M 

| 14 | 016 | SO | CTRL/N 

| 15 | O17 | SI | CTRL/O 

| 16 } 020 | DLE | CTRL/P 

| 17 | 021 | DCl | CTRL/Q*, XON 

| 18 | O22 | DC2 | CTRL/R 

| 19 | 023 | pcs | CTRL/S**, XOFF 

| 20 | 024 | Dc4 | CTRL/T 

| 21 | 025 | NAK | CTRL/U 

| 22 | O26 | SYN | CTRL/V 

| 23 | 027 | ETB | CTRL/W 
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ASCII Character Codes 


Table D-ls: 


Decimal 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


ASCII Character Codes 


Octal 


+ ~~ ~~ SOM +H 


q . 


WODMDUIDMNAWNrHOXYK- 


(Cont. ) 


CTRL/X 

CTRL/Y 

CTRL/Z, end of file 
Escape*** 

File Separator 
Group Separator 
Record Separator 
Unit Separator 
Space or blank 
Exclamation point 
Quotation mark 
Number sign 
Dollar sign 
Percent sign 
Ampersand 
Apostrophe 

Left parenthesis 
Right parenthesis 
Asterisk 

Plus 

Comma 

Hyphen or minus 
Period or decimal point 
Slash 

Zero 

One 

Two 

Three 

Four 

Five 

Six 

Seven 

Eight 

Nine 

Colon 

Semicolon 

Left angle bracket, "less than" 
sign 

Equal sign 

Right angle bracket, "greater than" 
sign 

Question mark 

At sign 


D-2 


Table D-l: 


oe s&s & s&s -«@ S&S -& of @2& © Be m= »- & &S& BP 2 © BSB 2 &© S&F SP BB s&s 2B Pee 2B ® eB & se &®F SB wv ese &«& SB 2B @® 2 FP 2 BP es SF &s SF se SF ee wp FP ew GS GG Be eae SP fF ese oe S&F & 


ASCII Character Codes (Cont.) 


KM ANK HK SSCHMNDWOWVOBZSHAUH TODA VAT YL 


Tue TQ hMOoMnoa -] 


Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 


NK XMS GPCCHANWOWOBA BZ PRU BDOABAMAIAWD PY 


ASCII Character Codes 


Left square bracket 


Backslash 


Right square bracket 


Circumflex 
Underscore 
Grave accent 


Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
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yu TM mhomN Yo WM 


ASCII Character Codes 


Table D-ls 


ASCII Character Codes 


tw — HANK KM ESCetnrRANQoos se 


DEL 


(Cont. ) 


Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 


Left brace 
Vertical line 


NK &E dad ecernrR OQUwWO SB Sr 


Right brace *x* 


Tilde *** 
Delete 

Reserved 
Reserved 
Reserved 
Reserved 
Index 

New line 


Horizontal tab set 


Vertical tab set 
Partial line down 
Partial line up 


Reverse Index 
Single shift 2 
Single shift 3 
Device control string 


Table D-ls 


ASCII Character Codes 


ASCII Character Codes (Cont. ) 


w ov i+ 


Reserved 

Reserved 

Reserved 

Control sequence introducer 
String terminator 


Reserved 

Inverted exclamation point 
Cent sign 

Pound sign 

Reserved 

Yen sign 

Reserved 

Section sign 

General currency sign 
Copyright sign 

Feminine ordinal indicator 
Angle quotation mark left 
Reserved 

Reserved 

Reserved 

Reserved 

Degree sign 

Plus/minus sign 
Superscript 2 

Superscript 3 

Reserved 

Micro sign 

Paragraph sign, pilcrow 
Middle dot 

Reserved 

Superscript l 

Masculine ordinal indicator 
Angle quotation mark right 
Fraction one quarter 
Fraction one half 

Reserved 

Inverted question mark 
Uppercase A with grave accent 
Uppercase A with acute accent 
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ASCII Character Codes 


Table D-l: 


228 


Z29 


ASCII Character Codes (Cont.) 


344 


Ch Cp Oh GM as bc 


FH. F4) Ft E+/ 


O: OVO?) Or OF Zr 


My: M2 o> On OV A Ki: a Oacy & 


Qo 


Uppercase A 
Uppercase. A 
Uppercase A 
umlaut mark 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
umlaut mark 
Uppercase I 
Uppercase I 
Uppetcase i 
Uppercase tI 
umlaut mark 
Reserved 
Uppercase N 
Uppercase O 
Uppercase O 
Uppercase O 
O 
O 


es es es es > 


Uppercase 
Uppercase 
umlaut mark 
Uppercase 
Uppercase O 
Uppercase U 
Uppercase UV 
Uppercase U 
Uppercase U 
umlaut mark 
Uppercase Y 
umlaut mark 
Reserved 


with 
with 
with 
with 
with 


with 


German lowercase 


Lowercase a 
Lowercase a 
Lowercase a 
Lowercase a 
Lowercase a 
umlaut mark 
Lowercase a 
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with 
with 
with 
with 
with 


with 


sc fe& ese ep = BB = & SF SG & SF 8s SB 2 & SBF 2 S&F S&F ss BB & S&F 2B 2 Ss wa = 2B Fe FF BP > oe we & 


Circumflex accent 
tilde 
diaeresis or 


ring 

dipthong 

cedilla 

grave accent 
acute accent 
circumflex accent 
diaeresis or 


grave accent 
acute accent 
circumflex accent 
diaeresis or 


tilde 

Grave. accent 
acute accent 
circumflex accent 
tilde 

diaeresis or 


OE ligature 


slash 

grave accent 
acute accent 
circumflex accent 
diaeresis or 


diaeresis or 


Sharp s 

grave accent 
acute accent 
circumflex accent 
tilde 

diaeresis or 


ring 


ASCII Character Codes 


some terminals, 


ALTMODE(ASCII 125) 


(ASCTE 12765 


keys, which appear on 
are translated internally into ESCAPE if the 


Table D-ls: ASCII Character Codes (Cont. ) 
pe ee ee ee ee ee ee ee ee ee ee eee “ 
| ASCII | 
Se +------- tree eee eee eee pee ne ee ee ee ee ee ee ee ee ee eee ee eee + 
| Decimal | Octal | Character | Remarks | 
+--+ 7+ ---- t------- Heer e ee eee eee , ae + 
| | | | | 
| 230 | 346 | 2 | Lowercase ae dipthong | 
| 234 ; "34 ¢ | Lowercase c with cedilla | 
| 232 ;- 350:. | & | Lowercase e with grave accent | 
| 233 joo e | Lowercase e with acute accent | 
| 234 | 352 | & | Lowercase e with circumflex accent | 
| 23: i Geoee 14 = | Lowercase e with diaeresis or | 
| | | | umlaut mark | 
| 236 | 354 | 1 | Lowercase i with grave accent | 
| 237 | oS: 3 1 | Lowercase i with acute accent | 
| 238 ; 356. || i | Lowercase i with circumflex accent | 
| 239 , 8357 © 1 | Lowercase i with diaeresis or | 
| | | | umlaut mark | 
| 240 | 360 | | Reserved | 
| 241 F 361 | n | Lowercase n with tilde | 
| 242 | 362 | 0 | Lowercase o with grave accent | 
| 243 r 363 | 6 | Lowercase o with acute accent | 
| 244 | 364 | 6 | Lowercase o with circumflex accent | 
| 245 | 365 | 6 | Lowercase o with tilde | 
| 246 3 BOO 7 fo) | Lowercase o with diaeresis or | 
| | | | umlaut mark | 
| 247 L eo i e | Lowercase oe ligature | 
| 248 | Ory: i w | Lowercase o with slash | 
| 249 Lo: | u | Lowercase u with grave accent | 
| 250 i ee a | Lowercase u with acute accent | 
| 251 > 373° | a | Lowercase u with circumflex accent | 
| Zoe | 374 | u | Lowercase u with diaeresis or | 
| | | | umlaut mark | 
| 253 | 25. | V | Lowercase y with diaeresis or | 
| | | | umlaut mark | 
| 254 | 376 | | Reserved | 
| 255 | @e7 J | Reserved | 
| * CTRL/Q, or XON, resumes output if the TTSYNC terminal | 
| characteristic is set. | 
| ** CTRL/S, or XOFF, stops output if the TTSYNC terminal | 
characteristic is set. | 
kx or PREFIX | 
| 
| 


ALT MODE terminal characteristic is set. 


-A- 


Alternate prefix character, 5-10 
Apostrophe substitution, 2-9 to 
2-10 
Arithmetic 
comparison operators, 3-10 
logical operators, 3-9 
operations, 3-9 
ASCII character codes, D-lt 
ASCII value conversion, 4-6 
Assignment statement, 2-4 
At sign (@) command, 1-5 
Automatic evaluation of symbols, 
2-10 


-B- 
Batch job execution, 1-7 
-C- 


CCL 
see Concise Command Language 
CHAIN statement, 1-8 
CLOSE command, 6-1ll 
CLOSE/LOG_FILE command, 9-6 
@ command, 1-2, 1-5 
Command levels, 2-6 
Command levels in nested command 
procedures, 7-7f 
Command line labels, 7-3 
Command procedure 
command levels in nested, 7-7f 
complex, 1-l 
controlling 
CTRL/C interrupts, 8-1l 
error conditions, 8-l 
execution flow, 7-1 
input, 5-1 
output, 5-1 
creating 
CREATE, 1-2 
EDT, 1-2 
temporary, 5-14 
DCL functions, 4-1 
definition, 1-1l 
displaying data, 5-8 


INDEX 


Command procedure (Cont. ) 
executing, 1-4 
batch mode, 1-7 
CHAIN statement, 1-8 
interactive level, 1-5 
login, 1-4 
RUN command, 1-8 
executing at interactive level, 
1-6f 
exiting, 7-8 
expressions, 3-l 
for system managers, 1-9 
formatting, 1-3 
interacting with, 5-1 
nesting, 1-8, 7-6 
passing 
control, 7-5 
data, 5-l 
parameters, 5-2 
returning data, 5-7 
samples, A-l 
Simple, 1-l 
system crashes, 1-9 
system startup, 1-9 
uses, l-l 
using comments in, 1-3 
using loops, 7-2 
Command synonyms, 2-8 
Commands 
at sign (@), 1-5 
CLOSE, 6-11 
CLOSE/LOG FILE, 9-6 
DELETE/SYMBOL, 2-14 
SEOD, 5-12 
EXIT, 7-8 
GOTO, 7-4 
IF, 7-1 
INQUIRE, 5-4 
ON, 8-4 
ON CONTROL C, 8-8 
ON keywords and actions, 8-5t 
OPEN, 6-2 
OPEN/LOG_FILE, 9-4 
READ, 6-5 
RUN, 1-8 
SET CONTROL=C, 8-9 
SET DATA, 5-10, 5-11 
SET ECHO, 9-1 


Index-l 


Commands (Cont. ) 

SET NOCONTROL=C, 8-9 

SET NOON, 8-6 

SET ON, 8-6 

SET VERIFY, 2-ll, 9-3 

SET/LOG FILE, 9-6 

SHOW SYMBOL, 2-12 

STOP, 7-10 

SUBMIT, 1-7 

WRITE, 6-8 
Comparing integer values, 3-10 
Comparing strings, 3-10 
Concatenating strings, 3-ll 
Concatenating symbols, 3-2 
Concise Command Language (CCL), 

1-9 
Converting values in expressions, 
3-4 

CRASH.COM, 1-9 
CTRL/C 

event flag, 8-7 

interrupt handling, 8-7 


-—D- 


Date/time string conversion, 4-9 

DCL functions 
arguments, 4-2 
command procedures, 4-1 
expressions, 3-3 
FSACCESS, 4-5 
FSASCII, 4-6 
FSCHR, 4-7 
FSCVTIME, 4-9 
FSEDIT, 4-10 
FSEDIT values, 4-llt 
FSINSTR, 4-12 
FSINTEGER, 4-14 
FSJOB, 4-15 
FSLEFT, 4-16 
FSLENGTH, 4-17 
FSMESSAGE, 4-18 
FSMID, 4-19 
FSNODE, 4-20 
FSPARSE, 4-21 
FSPRIVILEGE, 4-30 
FSPRIVILEGE keywords, 4-30t 
FSRIGHT, 4-34 
FSSEARCH, 4-35 
FSSTRING, 4-37 
FSTERMINAL, 4-38 
FSTIME, 4-39 


DCL functions (Cont.) 

FSTYPE, 4-40 

FSUSER, 4-41 

FSVERIFY, 4-42 

format, 4-1 

optional arguments, 4-2 

summary, 4-3t 
DELETE/SYMBOL command, 2-14 
Deleting symbols, 2-14 
Detached programs, 5-13 
Disabling CTRL/C interrupts, 8-9 
Displaying command procedures, 

9-1 to 9-7 

Displaying symbols, 2-12 


-E- 


Editing a string, 4-10 
Enabling CTRL/C interrupts, 8-9 
SEOD command, 5-12 
Error checking 
disabling with SET NOON command, 
8-6 
enabling with SET ON command, 
8-6 
Error conditions 
controlling with ON command, 
8-5 
error codes, 8-3t 
handling, 8-1l 
severity values, 8-2t 
stored as codes in SSTATUS, 8-l 
success codes, 8-3t 
Error messages, C-lt 
Evaluating symbols, 2-10 
Executing a command procedure at 
interactive level, 1-6f 
Executing command procedures, 1-4 
EXIT command, 7-8 
Exit status, 8-4 
Exiting from a command procedure, 
7-8 
Expressions 
command procedures, 3-l 
converting 
integers to strings, 3- 
Strings to integers, 3- 
DCL functions, 3-3 
determining types, 4-40 
integers, 3-3 
operators, 3-l, 3-7, 
quotation marks, 3-2 


6 
6 


3-8t 


Index-2 


Expressions (Cont. ) 
rules for determining type, 
3-5t 
String, 3-2 
symbols, 3-4 
types of values, 3-l 
value conversion, 3-4 


-F'- 
FSACCESS, 4-5 
FSASCII, 4-6 
FSCHR, 4-7 


FSCVTIME, 4-9 

FSEDIT, 4-10 
values, 4-llt 

FSINSTR, 4-12 

FSINTEGER, 4-14 

FSJOB, 4-15 

FSLEFT, 4-16 

FSLENGTH, 4-17 

FSMESSAGE, 4-18 

FSMID, 4-19 

FSNODE, 4-20 

FSPARSE, 4-21 
flag word values, 4-25t 
status word values, 4-23t 

FSPRIVILEGE, 4-30 
keywords, 4-30t 

FSRIGHT, 4-34 

FSSEARCH, 4-35 

FSSTRING, 4-37 

FSTERMINAL, 4-38 

FSTIME, 4-39 

FSTYPE, 4-40 

FSUSER, 4-41 

FSVERIFY, 4-42 

Files 
closing, 6-1l 
manipulating, 6-1 
opening, 6-2 
reading records, 6-5 
returning information, 4-35 
writing records, 6-8 

Flag word values for FSPARSE, 

4-25t 


Formatting command procedures, 


1-3 
-G- 


Global symbol table, 2-6 


Global symbols 
assigning, 2-4 
assigning strings, 2-6 
command synonyms, 2-8 
creating, 2-7 

GOTO command, 7-4 


-I- 


IF command, 7-1 
INQUIRE command, 5-4 
Integers 
comparing, 3-10 
converting 
to ASCII values, 4-7 
to strings, 3-6 
converting to strings, 4-37 


=J- 


Job access modes, 4-5 
Job number, 4-15 


-L- 


Labels 
rules for entering, 7-3 
storage, 7-4 
Local label table, 7-4 
Local symbol table, 2-6 
Local symbols 
assigning, 2 
strings, 2 
creating, 2- 
Log file 
terminal session, 9-3 
Logical operations, 3-9 
LOGIN.COM file, 1-4 
Loops, 7-2 


-4 
-5 
7 


to 9-7 


-N- 


Nested command procedure, 7-6 


Nested command procedures, 1-8, 


7-7£ 
of}. 


ON command, 8-4 

keywords and actions, 8-5t 
ON CONTROL_C command, 8-8 
OPEN command, 6-2 
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OPEN/LOG_FILE command, 9-4 
Operators 
arithmetic, 3-9 
arithmetic comparison, 3-10 
expressions, 3-l, 3-7, 3-8t 
logical, 3-9 
priority in expressions, 3-7 


-p- 


Parameters 


passing to a command procedure, 


5-2 
rules for passing, 5-2 
Privilege keywords, 4-30t 
Program 
detached within command 
procedure, 5-13 
exiting, 5-12 
passing symbol values, 5-14 
reading data, 5-8 
Supplying input 
command file, 5-9 
terminal, 5-10 
Project-programmer number, 4-41 
Prompt-string, 5-4 
Prompting for symbol values, 5-4 


-R- 


READ command, 6-5 
Reserved global symbols 
SSEVERITY, 8-1 
SSTATUS, 8-1 
RSTS/E and VAX/VMS command 
processor differences, B-l 
Rules for determining expression 
types, 3-5t 
RUN command, 1-8 


-S- 


SET CONTROL=C command, 8-9 
SET DATA command, 5-10, 5-11 
SET ECHO command, 9-1 

SET NOCONTROL=C command, 8-9 
SET NOON command, 8-6 

SET NOVERIFY command, 2-11 
SET ON command, 8-6 


SET TERMINAL/NOCONTROL=C command, 


8-8 
SET VERIFY command, 2-1ll, 9-3 


SET/LOG_FILE command, 9-6 
SSEVERITY symbol, 8-1 
Severity values, 8-2t 
Severity-level keywords, 8-4 
SHOW SYMBOL command, 2-12 
Signalling the end of data list, 
5-12 
START.COM, 1-9 
SSTATUS symbol, 8-1 
Status word values for FSPARSE, 
4-23t 
STOP command, 7-10 
String assignment statement, 2-6 
Strings 
comparing, 3-10 
concatenating, 3-2, 3-11 
converting to integers, 4-14 
determining length, 4-17 
editing, 4-10 
extracting substrings, 4-16, 
4-19, 4-34 
locating substrings, 4-12 
using in expressions, 3-2 
SUBMIT command, 1-7 
Summary of privileges, 4-30t 
Supplying data to program, 5-ll 
Symbol 
assigning null value, 5 
assignment statement, 2 
defining, 2-1 
definition, 2-1 
deleting a, 2-14 
displaying a, 2-12 
passing values to a program, 
5-14 
SSEVERITY, 8-1 
SSTATUS, 8-1 
storing, 2-6 
string assignment, 2-5 
undefined, 2-11 
use in expressions, 3-4 
Symbol assignment, 2-4 
Symbol names, 2-2 
abbreviating, 2-2 
case conversion, 2-2 
characters, 2-2 
length, 2-2 
restrictions, 2-2 
Symbol substitution, 2-8 
automatic evaluation, 2-10 
command synonyms, 2-8 
iterative substitution, 2-10 


-6 
-l 


Index-4 


Symbol substitution (Cont. ) 

overriding with an 
underscore(_), 2-8 

uSing apostrophes in, 2-9 
verifying, 2-1ll 

Symbol tables, 2-6 

Symbol types, 2-4 
determining, 4-40 
expressions, 2-4 
integer, 2-4 
String, 2-4 

Symbol values 
methods for assigning, 2-3 
prompting, 5-4 


-T- 
Terminal logging, 9-3 to 9-7 
Q- 


3 
CLOSE/LOG FILE, 9-6 


Terminal logging (Cont. ) 
OPEN/LOG_FILE, 9-4 
SET/LOG FILE, 9-6 

THEN keyword, 7-1 


-U- 
Undefined symbols, 2-ll, 4-40 
-V- 
VAX/VMS and RSTS/E command 
processor differences, B-l 
Verification status, 4-42 
Verifying symbol substitution, 
2-11 
-We- 


WRITE command, 6-8 
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